Skip to main content

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.

Ephemeral proxies can be enabled or disabled per tenant.

Invoke the Proxy

Detokenize and forward an HTTP request through the proxy.



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).



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

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

BT-PROXY-KEEP-ALIVEInjects header value into KEEP-ALIVE header when calling destination url
BT-PROXY-CONNECTIONInjects header value into CONNECTION header when calling destination url


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 "" \
-H "Content-Type: application/json" \
-X "POST" \
-d '{
"parameter1": "{{26818785-547b-4b28-b0fa-531377e99f4e}}",
"parameter2": "non-sensitive"


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:

proxy_erroranyA standard Basis Theory error

Custom Headers

BT-PROXY-DESTINATION-STATUSThis header contains the HTTP status code from the destination server.
If the BT-PROXY-DESTINATION-STATUS HTTP header is present and has an HTTP status code, the code represents the status code responded from the destination service. A 4xx code generally points to a problem with the integration to the destination, while a 5xx code suggests an issue with the destination service itself.

If the BT-PROXY-DESTINATION-STATUS HTTP header is not present, there is likely an integration or service problem. 4xx codes indicate issues on your end, while 5xx codes indicate problems with Basis Theory's service.