Skip to main content

Invoke Pre-Configured Proxy

The Basis Theory Proxy can be used to share tokenized data with trusted third parties via outbound HTTP requests. Pre-configured proxy requests are designed for recurring integrations with fixed destinations, allowing you to create a proxy instance with a unique key and predefined settings upfront. This approach is ideal for scenarios requiring consistent configurations, such as whitelisting destinations in production or applying custom request and response transforms with tailored logic.

Need to create a pre-configured proxy first? See Pre-Configured Proxies for setup instructions.

Invoke a pre-configured proxy instance.

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

Pre-configured proxies can be configured to either require authentication or allow anonymous requests. When authentication is required, a BT-API-KEY header must be provided with the request (see Authentication).

Unauthenticated proxy requests may be desired when receiving inbound requests from a third party. This would allow any caller who knows your unique proxy key to make inbound requests through the proxy without needing to share a Basis Theory API key with third parties.

Any authentication required by the destination service can be set on the request and will be forwarded through the proxy (for example, by setting an Authorization header).

Permissions

proxy:invoke

For existing proxies and to maintain backward compatibility we are also supporting token:use, however we recommend updating the permissions since that will be deprecated soon.

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.

The Proxy removes trailing slashes from the destination URL to ensure proper concatenation of contents following /proxy.

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

Reserved Headers

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
`BT-ENCRYPTED`	Allows passing Basis Theory Encrypted Data payloads in proxied requests

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.

Request

The unique key for a pre-configured proxy can either be supplied in a request header or a query string parameter.

Request with 'BT-PROXY-KEY' header
curl "https://api.basistheory.com/proxy" \
  -H "BT-API-KEY: <PRIVATE_API_KEY>" \
  -H "BT-PROXY-KEY: e29a50980ca5" \
  -H "Content-Type: application/json" \
  -X "POST" \
  -d '{
    "parameter1": "{{ 26818785-547b-4b28-b0fa-531377e99f4e }}",
    "parameter2": "non-sensitive"
  }'

Request with 'bt-proxy-key' query param
curl "https://api.basistheory.com/proxy?bt-proxy-key=e29a50980ca5" \
  -H "BT-API-KEY: <PRIVATE_API_KEY>" \
  -H "Content-Type: application/json" \
  -X "POST" \
  -d '{
    "parameter1": "{{ 26818785-547b-4b28-b0fa-531377e99f4e }}",
    "parameter2": "non-sensitive"
  }'

The BT-PROXY-URL header will be ignored when invoking Pre-Configured proxies

Detokenization

When making a request through the 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:

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

and a proxy request with the body:

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

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

Final Request Body
{
  "parameter1": "sensitive data",
  "parameter2": "non-sensitive data"
}

The proxy:invoke 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.

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

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

Custom Headers

The headers below are injected into proxied responses.

Header	Description
`BT-PROXY-DESTINATION-STATUS`	This 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.

Errors

Destination Errors

The proxy destination may return an error response, the format of which is completely controlled by the destination API. When an error occurs at the destination, the response is forwarded through the Basis Theory proxy as-is. In particular, these types of errors will have the same status code, headers, and response body as returned by the destination API.

You can identify whether an error was returned by the destination by inspecting the BT-PROXY-DESTINATION-STATUS response header, which will indicate the status code that Basis Theory received from the destination API.

Basis Theory Errors

If the proxy request is invalid (e.g., Basis Theory authentication fails, an invalid BT-PROXY-KEY is provided, an invalid detokenization expression is specified) or if a transform fails (e.g., code contains a syntax error, code throws an error), then the proxy will wrap a standard RFC 7807 error inside a proxy_error property to distinguish between Basis Theory errors and destination errors. For example, an invalid detokenization expression on a proxy request such as:

Request Body Template
{
    "invalid": "{{ unknown_token_id }}"
}

would result in the following error response:

Error Response
{
     "proxy_error": {
        "errors": {},
        "title": "Invalid proxy request",
        "status": 400,
        "detail": "Failed to detokenize some tokens: unknown_token_id"
    }
}

Transform Errors

Pre-configured proxies support custom request and response transforms, allowing you to execute tailored logic during proxy invocations. Errors that may occur during such steps may require appropriately handling to ensure robust proxy operations.

Please refer to Proxy Transform Errors to understand how such errors are thrown.

Encrypted Data

Use the BT-ENCRYPTED header to securely pass encrypted data in JWE (JSON Web Encryption) format to proxy destinations Generate these payloads using Basis Theory SDKs and reference them in your proxy request body with Liquid expressions, as shown below.

Single Token Request:

BT-ENCRYPTED header value
{
  "type": "card",
  "encrypted": "<JWE_STRING>"
}

You can reference the decrypted data in your proxy request body using the encrypted keyword with Liquid expressions:

curl "https://api.basistheory.com/proxy" \
  -H "BT-API-KEY: <PRIVATE_API_KEY>" \
  -H "BT-PROXY-URL: https://example.com/api" \
  -H "BT-ENCRYPTED: <BASE64_ENCODED_VALUE>" \
  -H "Content-Type: application/json" \
  -X "POST" \
  -d '{
    "accountNumber": "{{ encrypted | json: \"$.data.number\" }}",
    "expMonth": "{{ encrypted | json: \"$.data.expiration_month\" }}",
    "expYear": "{{ encrypted | json: \"$.data.expiration_year\" }}"
  }'

Multiple Token Requests:

BT-ENCRYPTED header value
{
  "creditCard": {
    "type": "card",
    "encrypted": "<JWE_STRING>"
  },
  "bankAccount": {
    "type": "bank",
    "encrypted": "<JWE_STRING>"
  },
  "personalInfo": {
    "type": "token",
    "encrypted": "<JWE_STRING>"
  }
}

You can reference the decrypted data in your proxy request body using the encrypted keyword with Liquid expressions:

curl "https://api.basistheory.com/proxy" \
  -H "BT-API-KEY: <PRIVATE_API_KEY>" \
  -H "BT-PROXY-URL: https://example.com/api" \
  -H "BT-ENCRYPTED: <BASE64_ENCODED_VALUE>" \
  -H "Content-Type: application/json" \
  -X "POST" \
  -d '{
    "cardNumber": "{{ encrypted | json: \"$.creditCard.data.number\" }}",
    "routingNumber": "{{ encrypted | json: \"$.bankAccount.data.routing_number\" }}",
    "personalInfo": "{{ encrypted | json: \"$.personalInfo.data.name\" }}"
  }'

Authentication
Permissions
Destination URLs
Reserved Headers
IP Whitelisting
Request
- Detokenization
Response
- Custom Headers
Errors
Encrypted Data