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.

Reserved Proxy Headers

ENTERPRISE

Proxies also include the ability to turn on additional features during a request, below outlines how to take advantage of each

Header	Description
BT-PROXY-KEEP-ALIVE	Injects header value into KEEP-ALIVE header when calling destination url
BT-PROXY-CONNECTION	Injects header value into CONNECTION header when calling destination url

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