Invoke Ephemeral Proxy
The Basis Theory Proxy can be used to share tokenized data with trusted third parties via outbound HTTP requests. Most 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.
Detokenize and forward an HTTP request through the proxy.
Authentication
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).
Permissions
proxy:invoke
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.
/proxy.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.
Request
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 "https://api.basistheory.com/proxy" \
-H "BT-API-KEY: <PRIVATE_API_KEY>" \
-H "BT-PROXY-URL: https://example.com/api" \
-H "Content-Type: application/json" \
-X "POST" \
-d '{
"parameter1": "{{ 26818785-547b-4b28-b0fa-531377e99f4e }}",
"parameter2": "non-sensitive"
}'
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:
{
"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 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.
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. |
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:
{
"invalid": "{{ unknown_token_id }}"
}
would result in the following error response:
{
"proxy_error": {
"errors": {},
"title": "Invalid proxy request",
"status": 400,
"detail": "Failed to detokenize some tokens: unknown_token_id"
}
}
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:
{
"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:
{
"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\" }}"
}'