Ephemeral Proxy

The Basis Theory Proxy can be used to share tokenized data with trusted third parties via outbound HTTP requests. Some outbound proxy requests simply need to detokenize some tokens in the request and forward the plaintext data to a destination API over HTTP. Ephemeral proxy requests are a good fit for this use case, as they don't require any up-front setup, and all configuration is self-contained within the proxy request.

Invoke the Proxy

Detokenize and forward an HTTP request through the proxy.

POST https://api.basistheory.com/proxy

GET https://api.basistheory.com/proxy

PUT https://api.basistheory.com/proxy

PATCH https://api.basistheory.com/proxy

DELETE https://api.basistheory.com/proxy

Authentication

Ephemeral proxy requests require a BT-API-KEY header (see Authentication) containing an API key for an authorized private application.

Any authentication required by the destination service can be set on the request and it will be forwarded through the proxy (for example, by setting an Authorization header).

Permissions

token:use

The token:use permission is required for each Container of Tokens you wish to detokenize through the Proxy. This permission is required to use the Proxy, even if there are no tokens being detokenized within your request.

It is recommended that you restrict which tokens the Proxy can detokenize by only granting token:use permission on the most-specific container of tokens that is required.

Request

A BT-PROXY-URL request header is required - its value defines the base URL to which the request will be proxied. See Destination URLs for more information.

curl "https://api.basistheory.com/proxy" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED" \
  -H "BT-PROXY-URL: https://example.com/api" \
  -H "Content-Type: application/json" \
  -X "POST" \
  -d '{
    "parameter1": "{{26818785-547b-4b28-b0fa-531377e99f4e}}",
    "parameter2": "non-sensitive"
  }'

Response

The raw response from the destination will be returned from the proxy, unless an error occurs within the Basis Theory Proxy while processing the request.

If an error occurs within the proxy (e.g. an invalid detokenization expression was found), then the following error response will be returned:

Attribute	Type	Description
proxy_error	any	A standard Basis Theory error