Skip to main content

What Is the Proxy?

It is a common need to share data between software systems via HTTP based APIs. But what if an outbound HTTP request from your system requires a piece of sensitive data that you have tokenized and do not want to access directly within your application? Or what if your API receives inbound HTTP requests that contain sensitive data that you wish to tokenize before it hits your servers?

The Proxy allows you to use tokens with HTTP APIs without needing to access sensitive data directly within your systems. This enables solving both these problems securely while keeping your systems out of compliance scope.

There are two options available when proxying HTTP requests:

  1. 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.
  2. 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.

Outbound Requests​

Outbound HTTP requests initiated from your system can include tokens within the request payload, and the proxy can detokenize and substitute the token data into the request before forwarding it to the desired destination. This makes it easy to share sensitive data with a third party without needing to first retrieve and manipulate this sensitive data on your servers.

How It Works​

Outbound Proxy Diagram

Your system initiates an outbound HTTP request to the Ephemeral Proxy or a Pre-Configured Proxy instance hosted by Basis Theory.

To include sensitive data in your request, you include token identifiers within expressions included in the request. These are patterns of the form {{<tokenId>}}, where <tokenId> is the id of a token created within your Basis Theory tenant. The request is transformed by evaluating each expression and substituting the resulting plaintext values within the request. Finally, the transformed request containing sensitive data is delivered to the configured destination URL.

The Proxy terminates the inbound TLS connection from your servers and initiates a new TLS connection to the destination in order to guarantee secure transmission of your sensitive token data.

Whatever the content type or HTTP method, any HTTP request can be sent through the Proxy. For further details, check out our API docs.

Guides​

Inbound Requests​

Third parties that integrate into your systems by calling an HTTP API may include sensitive data within their requests. Inbound HTTP requests into your system can be routed through the proxy to parse and tokenize sensitive pieces of data and substitute non-sensitive token identifiers into the request payload before it reaches your servers.

How It Works​

Inbound Proxy Diagram

You pre-configure a proxy instance, which provides you a unique URL to this proxy that can be shared with a third party integrator. The third party can then make HTTP requests to this URL that pass through the proxy before being forwarded on to your system.

The proxy instance can be configured with a request transform containing custom Node.js code that will execute within the proxy before the request is forwarded to your servers. This allows you to parse the request and tokenize sensitive data fields within the payload, substituting in non-sensitive tokens into the request. Your systems will receive a request containing the non-sensitive token identifiers that can be safely stored in your system.

Use a Custom Hostname for your Inbound Proxy​

You can use a custom hostname in front of your Inbound Proxy to brand it as your own. This allows you to have clients and partners call an API like https://secure.yourdomain.com instead of the default proxy domain https://api.basistheory.com/proxy?bt-proxy-key=....

All you need to do is the following:

  1. Own a domain with a valid SSL certificate
  2. Create a new Pre-Configured Proxy instance
  3. Create a CNAME record pointing your custom hostname to api.btproxy.cloud
  4. Navigate to the Basis Theory Portal, find your Proxy and enter its details page. Click the "Request Custom Hostname" button, fill in the necessary information, and submit the request
  5. Basis Theory support will inform you of the TXT record(s) to create to validate domain ownership
If you're ready to get started with white labeling your Basis Theory proxies, please reach out.

Guides​

FAQs​

How to Choose Between the Proxy and Serverless Reactors​

Basis Theory offers a number of out-of-the-box integrations to share your tokenized data with Third Party systems via our Serverless Reactor platform.

However, you may require an integration that is not yet supported, in which case you have a few options to choose from:

  • Create a custom Reactor containing the code required to integrate with the third party system (our serverless platform executes this code)
  • Use the Proxy to send the API request from your own application (your servers execute this code)

Using the Proxy can provide a quicker and lower configuration option for making custom HTTP requests to a third party API than writing and maintaining a Reactor.