What is Basis Theory’s Proxy?

What is the Proxy?

Tokenizing your data is only the first step. Once your data is safe and secure in your vault, you need to use that data in a meaningful way. The Basis Theory Proxy provides a simple interface to send HTTP requests containing sensitive data without your system needing the plaintext value. The Proxy requires minimal changes to your existing code and logic.

In its simplest form, the Proxy is simply a regular HTTP proxy: it receives a request, forwards the request to the intended destination, then passes the response back from the destination. 

For example, let's assume a third-party platform for credit checks needs Personally Identifiable Information (PII), such as a user's social security and driver's license numbers. Sending a simple HTTP request with a body is simple in most frameworks today. The only additional headers you need are the BT-PROXY-URL, which is the intended destination, and your BT-API-KEY.

curl "https://api.basistheory.com/proxy" \
  -H "Content-Type: application/json" \
  -H "Authorization: <BEARER-TOKEN>" \
  -H "BT-PROXY-URL: https://creditchecker.com/api"
  -H "BT-API-KEY: <BT-API-KEY>"
  -X "POST"  \
  -d '{
      "name": "John Doe",
      "ssn": "123-45-6789",
      "licenseNumber": "L123456789"
  }'

To make this request, you would first need to decrypt your tokens! This is where the real power of the Proxy comes: You don't need to pass the raw value, only the Token identifier.

curl "https://api.basistheory.com/proxy" \
  -H "Content-Type: application/json" \
  -H "Authorization: <BEARER-TOKEN>" \
  -H "BT-PROXY-URL: https://creditchecker.com/api" \
  -H "BT-API-KEY: <BT-API-KEY>" \
  -X "POST"  \
  -d '{
      "name": "John Doe",
      "ssn": "",
      "licenseNumber": ""
  }'

When the Proxy receives the request, it replaces the Token identifiers with the raw values (detokenization). The response is then passed straight through to you, regardless of whether it was successful or not. So you have now sent the sensitive data without the raw value touching your system!

Complex Data

A social security or driver’s license number is just a single value. What if you need to pass a complex object like a credit card? First, let’s look at what a fictional charge request might look like:

curl "https://api.creditcardcompany.com/charge" \
  -H "Content-Type: application/json" \
  -H "Authorization: <BEARER-TOKEN>" \
  -X "POST"  \
  -d '{ "card": { “number”: “4242424242424242”, “expiration_month”: 12, “expiration_year”: 2022, “cvc”: 123 } }'

Once you have a `card` Token, passing this request through the Proxy is just as simple as passing a social security number:

curl "https://api.basistheory.com/proxy" \
  -H "Content-Type: application/json" \
  -H "Authorization: <BEARER-TOKEN>" \
  -H "BT-PROXY-URL: https://api.creditcardcompany.com/charge" \
  -H "BT-API-KEY: <BT-API-KEY>" \
  -X "POST"  \
  -d '{ "card": “” }'

When the request hits the Proxy, the Token Identifier replaces the entire card object. This example is admittedly convenient: the properties on the card object in the request match the schema for the Basis Theory card Token Type.

So what if the merchant required the expiration date to be in YYYY/MM format?

Data Expression and Transformation

Detokenization occurs on requests when a detokenization expression is detected. As we’ve seen above, the simplest form of a detokenization expression is 0.

When detokenized, the plaintext data in the token replaces the expression with a simple string or a complex object in the earlier examples. (Note: only Token Identifiers are detokenized, anything else inside of will be ignored.)

Basis Theory supports JSON Path transformations to further work with complex data types. These transformations allow you to grab only the pieces of data you need for a request. Using these transformations, you can easily format the expiration date as YYYY/MM: ‍

curl "https://api.basistheory.com/proxy" \
  -H "Content-Type: application/json" \
  -H "Authorization: <BEARER-TOKEN>" \
  -H "BT-PROXY-URL: https://api.creditcardcompany.com/charge" \
  -H "BT-API-KEY: <BT-API-KEY>" \
  -X "POST"  \
  -d '{
    "card": {
      "number": "",
      "expiration": "/",			
      "cvc": "",
    }
  }'

Migrating Your App to Use the Proxy

One concern for any development team when considering a new product is the effort involved in migrating the existing app to use that new product. The Basis Theory Proxy is designed to make that transition as simple as possible.

Instead of having to build custom Reactor Formulas and alter your business logic to call the Reactor, you can simply repurpose your existing HTTP call. The only code changes required to use the proxy are to pass the Token Identifier in the body instead of the raw value and add the BT-API-KEY and BT-PROXY-URL headers.

By changing only a few lines of code, your system is now that much closer to compliance!

Interested in trying Proxy? Register for a free account and get to production without a credit card today.