Skip to main content


The Basis Theory Proxy provides a simple way to facilitate the secure transfer of sensitive data via HTTP API calls. The Proxy can be configured to sit in front of your API to transform or tokenize parts of an inbound request, keeping sensitive data from touching your systems. It can also be used to detokenize and share sensitive data with a third party via outbound HTTP requests. To learn more about the Proxy and supported use cases, check out What is the Proxy?.

Proxies can be utilized for both inbound and outbound calls for things such as webhooks, enabling 3rd parties to call your API or making API calls to 3rd party partners and providers.

Types of Proxies

There are two types of proxies, each supporting its own configuration and usage patterns:

  1. Ephemeral Proxy: Simply invoke the proxy API endpoint and specify the configuration in your request. No configuration is needed ahead of time. This option is best for basic use cases that don't require the use of request or response transforms.
  2. Pre-Configured Proxies: First configure a proxy instance, then invoke it by its unique key. This option is best for more complex use cases requiring custom request or response transforms.


Destination URLs

The configured destination URL must use HTTPS with DNS as the host (explicit IP addresses are not allowed). Destinations must use HTTPS >= TLSv1.2.

The destination URL will serve as the base URL for the proxied request, and any path and/or query parameters on your request path (/proxy/**) will be appended to the base URL before forwarding the request.

For example, sending a proxy request to and including the header BT-PROXY-URL= will result in the request being forwarded to

If the destination endpoint takes more than 25 seconds to respond, a 408 Request Timeout error will be returned.

Reserved Proxy Request 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

Custom Proxy Response 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.

IP Whitelisting

Some 3rd party services may require whitelisting of Basis Theory IP addresses to allow communication. You can find our IP list here.

We can also support single dedicated outbound IP addresses. Please reach out to our support team if you have specific security requirements that mandate this configuration.


When making a request through either type of Proxy, Basis Theory will attempt to detokenize any expressions present in the request and inject the raw token data in the request body before it is sent to the downstream destination.

For example, given a token:

"id": "26818785-547b-4b28-b0fa-531377e99f4e",
"data": "sensitive data"

and a proxy request with the body:

"parameter1": "{{26818785-547b-4b28-b0fa-531377e99f4e}}",
"parameter2": "non-sensitive data"

then the following request body will be sent to the destination:

"parameter1": "sensitive data",
"parameter2": "non-sensitive data"

The token:use permission is required in order to detokenize tokens within a proxy request. At most, 100 tokens may be detokenized within a single proxy request. You can find more information about the supported detokenization expressions here.

For more detailed examples about how to detokenize within the Proxy, check out our Detokenization Examples.