Skip to main content

Ephemeral Proxy

The Basis Theory Proxy can be used to share tokenized data with trusted third parties via outbound HTTP requests. Some 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.

Ephemeral proxies can be enabled or disabled per tenant.

Invoke the Proxy

Detokenize and forward an HTTP request through the proxy.

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

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

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.

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

Encrypted Token Header

The BT-ENCRYPTED header allows you to pass encrypted token requests to proxy destinations. This header accepts a base64-encoded token request containing encrypted JWE (JSON Web Encryption) data instead of plaintext.

Header Format

The BT-ENCRYPTED header should contain a base64-encoded token request with the following structure:

Single Token Request:

{
  "type": "card",
  "encrypted": "<JWE_STRING>"
}

Multiple Token Requests:

{
  "creditCard": {
    "type": "card",
    "encrypted": "<JWE_STRING>"
  },
  "bankAccount": {
    "type": "bank",
    "encrypted": "<JWE_STRING>"
  },
  "personalInfo": {
    "type": "token",
    "encrypted": "<JWE_STRING>"
  }
}

To see how to use this header with the proxy, see Using Encrypted Data in Proxy Requests. You can encrypt a token and get the JWE data with the Basis Theory SDKs.

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"
  }'

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

Using Encrypted Data in Proxy Requests

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_TOKEN_REQUEST>" \
  -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\" }}"
  }'

For multiple token requests, you can access specific tokens. The object key is used to reference the token in the Liquid expression.

// Token requests before encryption:
{
  "creditCard": {
    "type": "card",
    "encrypted": "<JWE_STRING>"
  },
  "bankAccount": {
    "type": "bank",
    "encrypted": "<JWE_STRING>"
  },
  "personalInfo": {
    "type": "token",
    "encrypted": "<JWE_STRING>"
  }
}

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_MULTIPLE_TOKEN_REQUEST>" \
  -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\" }}"
  }'

Custom Headers

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.

Invoke the Proxy