Skip to main content

Collect Inbound Data to API

This guide will show you how to collect data in your API without touching the data.

Key concepts in this guide:

Getting Started​

To get started, you will need a Basis Theory account.

Next you will need a Management Application in order to provision the components in this guide.

Click here to create a Management Application or login to your Basis Theory account and create a new application from the Full Management Access template.

Save the API Key from the created Management Application as it will be used in this guide to provision everything.

Create a Public Application​

We need a Public Application to create tokens from the inbound data before it reaches our API:

curl "https://api.basistheory.com/applications" \
  -H "BT-API-KEY: test_1234567890" \
  -H "Content-Type: application/json" \
  -X "POST" \
  -d '{
    "name": "Collect Public App",
    "type": "public",
    "permissions": [ "token:create" ]
  }'

Save the application id from the created Public Application as it will be used to create the proxy.

Create the Proxy​

We will create a Proxy capable of intercepting inbound calls to our API, tokenize part of the request, and send the modified request to our API.

The Basis Theory Proxy leverages a request transform, which is executed in a Node.js 16 runtime. The following code will handle tokenizing the request:

module.exports = async function (req) {
  const socialSecurityNumber = req.args.body.socialSecurityNumber;

  const token = await req.bt.tokens.create({
    type: "token",
    data: socialSecurityNumber
  });

  return {
    headers: req.args.headers,
    body: {
      ...req.args.body,
      socialSecurityNumber: token.id
    }
  };
};

This code will read in the socialSecurityNumber property from the request body, tokenize it with a pre-configured Basis Theory JS SDK instance, and update the request body replacing the original socialSecurityNumber value with id of the token.

We need to create an instance of a Proxy with the previous code as a request_transform.

First, let's store the JavaScript code as a variable. In your terminal, run the following:

javascript='module.exports = async function (req) {
  const socialSecurityNumber = req.args.body.socialSecurityNumber;

  const token = await req.bt.tokens.create({
    type: "token",
    data: socialSecurityNumber
  });

  return {
    headers: req.args.headers,
    body: {
      ...req.args.body,
      socialSecurityNumber: token.id
    }
  };
};'

Next, we need to create an instance of a Proxy, with the variable we created:

curl "https://api.basistheory.com/proxies" \
  -H "BT-API-KEY: test_1234567890" \
  -H "Content-Type: application/json" \
  -X "POST" \
  -d '{
    "name": "Inbound Proxy Example",
    "destination_url": "https://echo.basistheory.com/anything",
    "request_transform": {
      "code": '$(echo $javascript | jq -Rsa .)'
    },
    "application": {
      "id": "45c124e7-6ab2-4899-b4d9-1388b0ba9d04"
    },
    "require_auth": false
  }'

Be sure to replace test_1234567890 with the Management API Key you created in the Getting Started step and replace 45c124e7-6ab2-4899-b4d9-1388b0ba9d04 with the id of the Public Application you created in the Getting Started step.

Save the proxy key from the response as it will be used to invoke the proxy.

This is using jq to replace the JavaScript code as a JSON escaped string value. It will create a new Proxy instance where we will run the request_transform on the inbound Proxy request against the body and headers of the request. The proxy will then send the request to our destination_url, which should be your API URL. In this guide, we are going to use https://echo.basistheory.com/anything so we can see the tokenized socialSecurityNumber.

Invoke the Proxy​

Now that we have our Proxy created, we need to invoke it. In your terminal run the following:

curl "https://api.basistheory.com/proxy" \
  -H "BT-PROXY-KEY: TDEyQmkhQMpGiZd13FSRQ9" \
  -H "Content-Type: application/json" \
  -X "POST" \
  -d '{
    "socialSecurityNumber": "123-45-6789"
  }'

Be sure to replace TDEyQmkhQMpGiZd13FSRQ9 with the key of the Proxy you created in the Create the Proxy step.

If successful, you should see an output similar to this:

{
  "args": {},
  "data": "{\"socialSecurityNumber\":\"8b4f3aab-abc6-423f-86b9-c368919bdc65\"}",
  "files": {},
  "form": {},
  "headers": {
    "Accept": "*/*",
    "Accept-Encoding": "gzip",
    "Bt-Trace-Id": "0us+cYwAAAACCDkUl9kKnRY3yEEMzpsZ/Q0hHRURHRTE2MTkAMTYzY2E1ODMtNjQ3MS00MTc3LTg0ZGItZTA4MzBlZGFiODUw",
    "Content-Length": "63",
    "Content-Type": "application/json",
    "Disguised-Host": "echo.basistheory.com",
    "Host": "echo.basistheory.com",
    "User-Agent": "curl/7.85.0",
    "X-Forwarded-Tlsversion": "1.2",
    "X-Original-Url": "/anything",
    "X-Waws-Unencoded-Url": "/anything"
  },
  "json": {
    "socialSecurityNumber": "8b4f3aab-abc6-423f-86b9-c368919bdc65"
  },
  "method": "POST",
  "url": "https://echo.basistheory.com/anything"
}

Notice that the socialSecurityNumber was successfully replaced with our tokenized value.

Now that you have your token, check out our guide on how to send data to a third-party!

Learn More​