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

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

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