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.

Common Use Cases​

Share Sensitive Data with a Third Party​

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.

Receive Sensitive Data from a Third Party​

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.

Upgrade an Existing System​

In existing systems with sensitive data you wish to secure, this data can be migrated and tokenized with Basis Theory. Once safely tokenized, your systems still need to utilize this data with your existing HTTP calls without pulling the raw values back into your system. For this, you can leverage the Proxy in order to minimize the impact of this change on your existing codebase.

How It Works​

Outbound Proxy Requests​

Your system initiates an outbound HTTP request to the Proxy hosted by Basis Theory. The request is transformed by evaluating any expressions included in the request (patterns of the form {{<tokenId>}}, where <tokenId> is the id of a token created within your tenant). Any detokenization expressions will be replaced with the detokenized data value of this token. Finally, the request is delivered to the configured destination URL.

Outbound Proxy Diagram

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. For this reason, we require the destination servers to support TLSv1.2+ and that the provided destination URL uses https.

Whatever the content type or HTTP method, any HTTP request can be sent through an ephemeral proxy simply by adding the headers BT-API-KEY and BT-PROXY-URL. For example:

curl "https://api.basistheory.com/proxy" \
      -H "BT-API-KEY: key_NS21v84n7epsSc5WzoFjM6" \
      -H "BT-PROXY-URL: https://my-destination-api.com" \
      -H "Content-Type: application/json" \
      -X "POST" \
      -d '{
            "sensitive": "{{e51b0ff4-aa80-407a-b628-3909c26ff397}}",
            "nonSensitive": "plaintext data can go here"
        }'

For further details about how to use the Proxy, check out our API docs.

Inbound Proxy Requests​

You pre-configure a proxy instance and share a unique URL to this proxy 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 executes within the proxy before the request is forwarded to your servers. This allows you to inspect 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.

Samples​

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 Formula 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 custom reactor formula.