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:
- 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.
- 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 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
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> 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.
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
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.
Create a custom domain for your inbound proxy
You can create a custom domain for your inbound proxy to make it seamless to integrate into your existing application. This allows you to use a
https://secure.yourdomain.com instead of the default proxy domain
https://api.basistheory.com/proxy to invoke your inbound proxy.
All we would need to do is the following:
- Configure a Basis Theory proxy instance
- Own a domain with a valid SSL certificate
- We register your domain with our DNS provider
- Create a CNAME record pointing to
- Create a new TXT record to validate ownership
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.