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:
- 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.
- 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.
408 Request Timeout error will be returned.Reserved Proxy Request 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 |
Custom Proxy Response Headers
| Header | Description |
|---|---|
BT-PROXY-DESTINATION-STATUS | This header contains the HTTP status code from the destination server. |
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.
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, 20 tokens may be detokenized within a single proxy request. You can find more information about the supported detokenization expressions here.