Proxies

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.

Configuration

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 https://api.basistheory.com/proxy/foo/bar?param=value and including the header BT-PROXY-URL=https://example.com/api will result in the request being forwarded to https://example.com/api/foo/bar?param=value.

If the destination endpoint takes more than 30 seconds to respond, a 504 Gateway Timeout error will be returned.

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.

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

Detokenization

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.