NAV
cURL Node.js .NET Python BETA

Get Started

Reference

Other Docs

More

Introduction

The Basis Theory API is organized around REST. Our API is built with a predictable resource-oriented structure, uses JSON-encoded requests and responses, follows standard HTTP verbs/responses, and uses industry standard authentication.

You are able to create different Tenants within your Basis Theory account to enable you to segment your test environments from your core production data. Tenants serve as a logical grouping for each of your systems to interact with Basis Theory without affecting each other.

What is Basis Theory?

Our software becomes a core part of your infrastructure enabling you to quickly encrypt, tokenize, and store any payload securely. Your token infrastructure can be used to protect data at rest, as it passes between your own internal systems, or how it's permissioned and shared with third parties.

Getting started

Before You Begin

If you don't have an account

To begin taking advantage of the Basis Theory platform, you’ll need to create an account and Tenant through our Portal.

If you have an account

Check out our API Reference documentation below, or go to our Getting Started section if you’re unsure of where to go next.

Try with Postman

Create a fork of our Basis Theory API workspace, this has pre-configured sample API calls enabling you to quickly try out our API.

Run in Postman

Install SDK

Install SDK

npm install --save @basis-theory/basis-theory-js
dotnet add package BasisTheory.net 
pip install basistheory

Our SDKs enable you to quickly and easily integrate with the API. Select one of the language tabs to see instructions on how to install the SDK and view code examples in that language.

If you don't see your language listed, contact us about getting an official SDK added in your preferred language.

Authentication

Request

curl "https://api.basistheory.com" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED"
import { BasisTheory } from '@basis-theory/basis-theory-js';

// at instance
const bt = await new BasisTheory().init('key_N88mVGsp3sCXkykyN2EFED');

// per call
const bt = await new BasisTheory().init();

const applications = await bt.applications.list({}, {
  apiKey: 'key_N88mVGsp3sCXkykyN2EFED'
});
using BasisTheory.net.Tokens;

// At service
var client = new TokenClient("key_N88mVGsp3sCXkykyN2EFED");

// Per call
var client = new TokenClient();

client.GetAsync(requestOptions: new RequestOptions {
  ApiKey = "key_N88mVGsp3sCXkykyN2EFED"
});
import basistheory
from basistheory.api import tokens_api

# At instance
api_client = basistheory.ApiClient(configuration=basistheory.Configuration(api_key="key_N88mVGsp3sCXkykyN2EFED"))
client = tokens_api.TokensApi(api_client)

# Per call
client.list(request_options=basistheory.RequestOptions(api_key="key_N88mVGsp3sCXkykyN2EFED"))

Basis Theory uses API keys to allow access to the API.

Basis Theory requires the API key to be included in all API requests to the server in a header that looks like the following:

BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED

Request Correlation

Correlation ID Example:

curl "https://api.basistheory.com" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED" \
  -H "BT-TRACE-ID: aa5d3379-6385-4ef4-9fdb-ca1341572153"
import { BasisTheory } from '@basis-theory/basis-theory-js';

const bt = await new BasisTheory().init('key_N88mVGsp3sCXkykyN2EFED');

const applications = await bt.applications.list({}, {
  correlationId: 'aa5d3379-6385-4ef4-9fdb-ca1341572153'
});
using BasisTheory.net.Tokens;

var client = new TokenClient("key_N88mVGsp3sCXkykyN2EFED");

client.GetAsync(requestOptions: new RequestOptions {
  CorrelationId = "aa5d3379-6385-4ef4-9fdb-ca1341572153"
});
import basistheory
from basistheory.api import tokens_api

# At instance
api_client = basistheory.ApiClient(configuration=basistheory.Configuration(api_key="key_N88mVGsp3sCXkykyN2EFED"))
client = tokens_api.TokensApi(api_client)

# Per call
client.list(request_options=basistheory.RequestOptions(correlation_id="aa5d3379-6385-4ef4-9fdb-ca1341572153"))

Basis Theory utilizes Correlation IDs to assist with request tracing, logging, and debugging.

All API endpoints accept a client-provided Correlation ID if sent with the BT-TRACE-ID HTTP header within POST, PUT, PATCH, DELETE methods.

If a BT-TRACE-ID Correlation ID is not provided by the client, a new Correlation ID will be generated by the Basis Theory API.

Pagination

Request

curl "https://api.basistheory.com/applications?page=2&size=10" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED"
import { BasisTheory } from '@basis-theory/basis-theory-js';

const bt = await new BasisTheory().init('key_N88mVGsp3sCXkykyN2EFED');

const applications = await bt.applications.list({
  page: 2,
  size: 10
});
using BasisTheory.net.Applications;

var client = new ApplicationClient("key_N88mVGsp3sCXkykyN2EFED");

var applications = client.GetAsync(new ApplicationGetRequest {
  Page = 2,
  PageSize = 10
});

Response

{
  "pagination": {
    "total_items": 924,
    "page_number": 2,
    "page_size": 10,
    "total_pages": 93
  },
  "data": [
    {...},
    {...},
    {...}
  ]
}

All List endpoints support pagination to allow bulk fetching multiple items. Each List endpoint shares a common response structure. Examples of these requests can be seen in List Applications, List Tokens, and List Atomic Cards

Query Parameters

Parameter Required Type Default Description
page false integer 1 Page number of the results to return
size false integer 20 Number of results per page to return. Maximum size of 100 results.

Pagination Object

Attribute Type Description
pagination pagination metadata Pagination metadata for the response
data array Query results of the request. See list endpoint resource for response schema definition

Pagination Metadata Object

Attribute Type Description
total_items integer Total number of items in the Tenant
page_number integer Current page number. Should match page query parameter.
page_size integer The size of each page. Should match size query parameter.
total_pages integer The total number of pages.

Errors

{
  "errors": {
    "additionalProp1": [
      "string"
    ],
    "additionalProp2": [
      "string"
    ],
    "additionalProp3": [
      "string"
    ]
  },
  "type": "string",
  "title": "string",
  "status": 400,
  "detail": "string",
  "instance": "string"
}
import { BasisTheory } from '@basis-theory/basis-theory-js';

try {
  const bt = await new BasisTheory().init('key_N88mVGsp3sCXkykyN2EFED');
  const application = await bt.applications.create({ ... });
} catch (e) {
  console.log(e.status); // HTTP status code
  console.log(e.data); // HTTP Response body
  console.log(e.data.errors);
}

Response

Attribute Type Description
title string A short, human-readable summary of the problem
detail string A human-readable explanation specific to this occurrence of the problem
errors.{property} array An array of human readable error messages returned per request {property}
status integer HTTP status code of the response

Error Codes

Error Code Meaning
400 Invalid request body
401 A missing or invalid BT-API-KEY was provided
403 The provided BT-API-KEY does not have the required permissions
404 Request entity was not found
422 Request does not satisfy requirements for processing
429 Request has been rate limited
500 Something went wrong on Basis Theory's side

Reactor Errors

When calling POST */react endpoints, vendor-specific errors are translated to the same response schema as Basis Theory Errors. Additional response codes may be returned on calls to POST */react mapped from vendor-specific errors.

Reactor Error Codes

Error Code Meaning Common Scenarios
400 Bad Request
  • Missing or invalid request properties when processing the request with the vendor
  • Invalid Reactor Configuration
401 Authentication Error
  • Invalid or unknown credentials
  • Credentials are valid, but lack permission to complete the operation
402 Invalid Payment Method
  • Expired Card
  • A test card or bank account was used in a production environment, or vice-versa
  • The vendor denied the card or bank account
422 Unprocessable Entity
  • Reactor Formula code is not a valid function
429 Rate Limit Error
  • The vendor responded with a 429 HTTP response code
500 Reactor Runtime Error
  • An unhandled exception occurred
  • The vendor responded with a 5XX HTTP response code
  • Vendor connection failure

Limits

The Basis Theory API has rate limits applied to ensure the speed and consistency of our systems.

Error Codes

Error Code Meaning
429 Request has been rate limited

Applications

Your ability to authenticate to the API is granted by creating Applications, each Application type has different usages to create the most fine-grained control over your tokens and infrastructure possible. Below, we describe each Application Type and their usages.

Application Object

Attribute Type Description
id uuid Unique identifier of the Application which can be used to get an Application
tenant_id uuid The Tenant ID which owns the Application
name string The name of the Application
key string The API key which should be used for authenticating against Basis Theory API endpoints
type string Application type of the Application
permissions array List of permissions for the Application
created_by uuid (Optional) The ID of the user or Application that created the Application
created_at date (Optional) Created date of the Application in ISO 8601 format
modified_by uuid (Optional) The ID of the user or Application that last modified the Application
modified_at date (Optional) Last modified date of the Application in ISO 8601 format

Application Types

Name Type Description
Server-to-Server server_to_server Used for tokenizing, retrieving, and decrypting data within backend services where the API key can be secured
Client-side Application public Used for tokenizing data directly within your mobile or browser application
Elements elements Used for tokenizing data with the Basis Theory Elements module
Management management Used for managing all aspects of your token infrastructure such as creating an Application

Create Application

Request

curl "https://api.basistheory.com/applications" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED" \
  -H "Content-Type: application/json" \
  -X "POST" \
  -d '{
    "name": "My Example App",
    "type": "server_to_server",
    "permissions": [
      "token:general:create",
      "token:general:read:low"
      "token:pci:create",
      "token:pci:read:low",
    ]
  }'
import { BasisTheory } from '@basis-theory/basis-theory-js';

const bt = await new BasisTheory().init('key_N88mVGsp3sCXkykyN2EFED');

const application = await bt.applications.create({
  name: 'My Example App',
  type: 'server_to_server',
  permissions: [
    'token:general:create',
    'token:general:read:low',
    'token:pci:create',
    'token:pci:read:low',
  ],
});
using BasisTheory.net.Applications;

var client = new ApplicationClient("key_N88mVGsp3sCXkykyN2EFED");

var application = await client.CreateAsync(new Application {
  Name = "My Example App",
  Type = "server_to_server",
  Permissions = new List<string> {
    "token:general:create",
    "token:general:read:low",
    "token:pci:create",
    "token:pci:read:low"
  }
});
# Coming Soon!

Response

{
  "id": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
  "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
  "name": "My Example App",
  "key": "key_FZ8RmaxoGc73lbmF2cpmUJ",
  "type": "server_to_server",
  "permissions": [
    "token:general:create",
    "token:general:read:low",
    "token:pci:create",
    "token:pci:read:low"
  ],
  "created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
  "created_at": "2020-09-15T15:53:00+00:00"
}

POST https://api.basistheory.com/applications

Create a new Application for the Tenant.

Permissions

application:create

Request Parameters

Attribute Required Type Default Description
name true string null The name of the Application. Has a maximum length of 200
type true string null Application type of the application
permissions false array [] Permissions for the application

Response

Returns an Application if the application was created. Returns an error if there were validation errors, or the application failed to create.

List Applications

Request

curl "https://api.basistheory.com/applications" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED"
import { BasisTheory } from '@basis-theory/basis-theory-js';

const bt = await new BasisTheory().init('key_N88mVGsp3sCXkykyN2EFED');

const applications = await bt.applications.list();
using BasisTheory.net.Applications;

var client = new ApplicationClient("key_N88mVGsp3sCXkykyN2EFED");

var applications = await client.GetAsync();
# Coming Soon!

Response

{
  "pagination": {...}
  "data": [
    {
      "id": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
      "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
      "name": "My Example App",
      "type": "server_to_server",
      "permissions": [
        "token:general:create",
        "token:general:read:low",
        "token:pci:create",
        "token:pci:read:low"
      ],
      "created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
      "created_at": "2020-09-15T15:53:00+00:00",
      "modified_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
      "modified_at": "2021-03-01T08:23:14+00:00"
    },
    {...},
    {...}
  ]
}

GET https://api.basistheory.com/applications

Get a list of applications for the Tenant.

Permissions

application:read

Query Parameters

Parameter Required Type Default Description
id false array [] An optional list of application ID's to filter the list of applications by

Response

Returns a paginated object with the data property containing an array of applications. Providing any query parameters will filter the results. Returns an error if applications could not be retrieved.

Get an Application

Request

curl "https://api.basistheory.com/applications/fe1f9ba4-474e-44b9-b949-110cdba9d662" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED"
import { BasisTheory } from '@basis-theory/basis-theory-js';

const bt = await new BasisTheory().init('key_N88mVGsp3sCXkykyN2EFED');

const application = await bt.applications.retrieve('fe1f9ba4-474e-44b9-b949-110cdba9d662');
using BasisTheory.net.Applications;

var client = new ApplicationClient("key_N88mVGsp3sCXkykyN2EFED");

var application = await client.GetByIdAsync("fe1f9ba4-474e-44b9-b949-110cdba9d662");
# Coming Soon!

Response

{
  "id": "fe1f9ba4-474e-44b9-b949-110cdba9d662",
  "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
  "name": "My Management App",
  "type": "management",
  "permissions": [
    "application:create",
    "application:read"
  ],
  "created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
  "created_at": "2020-09-15T15:53:00+00:00",
  "modified_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
  "modified_at": "2021-03-01T08:23:14+00:00"
}

GET https://api.basistheory.com/applications/{id}

Get an application by ID in the Tenant.

Permissions

application:read

URI Parameters

Parameter Required Type Default Description
id true uuid null The ID of the application

Response

Returns an Application with the id provided. Returns an error if the application could not be retrieved.

Get an Application by Key

Request

curl "https://api.basistheory.com/applications/key" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED"
import { BasisTheory } from '@basis-theory/basis-theory-js';

const bt = await new BasisTheory().init('key_N88mVGsp3sCXkykyN2EFED');

const application = await bt.applications.retrieveByKey();
using BasisTheory.net.Applications;

var client = new ApplicationClient("key_N88mVGsp3sCXkykyN2EFED");

var application = await client.GetByKeyAsync();
# Coming Soon!

Response

{
  "id": "fe1f9ba4-474e-44b9-b949-110cdba9d662",
  "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
  "name": "My Management App",
  "type": "management",
  "permissions": [
    "application:create",
    "application:read"
  ],
  "created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
  "created_at": "2020-09-15T15:53:00+00:00",
  "modified_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
  "modified_at": "2021-03-01T08:23:14+00:00"
}

GET https://api.basistheory.com/applications/key

Get an application by key in the Tenant. Will use the BT-API-KEY header to lookup the application.

Permissions

application:read

Response

Returns an Application for the provided BT-API-KEY. Returns an error if the application could not be retrieved.

Update Application

Request

curl "https://api.basistheory.com/applications/fb124bba-f90d-45f0-9a59-5edca27b3b4a" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED" \
  -H "Content-Type: application/json"
  -X "PUT" \
  -d '{
    "name": "My Example App",
    "permissions": [
      "application:create",
      "application:read"
    ]
  }'
import { BasisTheory } from '@basis-theory/basis-theory-js';

const bt = await new BasisTheory().init('key_N88mVGsp3sCXkykyN2EFED');

const application = await bt.applications.update('fb124bba-f90d-45f0-9a59-5edca27b3b4a', {
  name: 'My Example App',
  permissions: [
    'token:general:create',
    'token:general:read:low',
    'token:pci:create',
    'token:pci:read:low',
  ],
});
using BasisTheory.net.Applications;

var client = new ApplicationClient("key_N88mVGsp3sCXkykyN2EFED");

var application = await client.UpdateAsync("fb124bba-f90d-45f0-9a59-5edca27b3b4a", 
  new Application {
    Name = "My Example App",
    Permissions = new List<string> {
      "token:general:create",
      "token:general:read:low",
      "token:pci:create",
      "token:pci:read:low"
    }
  }
);
# Coming Soon!

Response

{
  "id": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
  "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
  "name": "My Example App",
  "type": "management",
  "permissions": [
    "application:create",
    "application:read"
  ],
  "created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
  "created_at": "2020-09-15T15:53:00+00:00",
  "modified_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
  "modified_at": "2021-03-01T08:23:14+00:00"
}

PUT https://api.basistheory.com/applications/{id}

Update an application by ID in the Tenant.

Permissions

application:update

URI Parameters

Parameter Required Type Default Description
id true uuid null The ID of the application

Request Parameters

Attribute Required Type Default Description
name true string null The name of the application. Has a maximum length of 200
permissions false array [] Permissions for the application

Response

Returns an Application if the application was updated. Returns an error if there were validation errors, or the application failed to update.

Regenerate API Key

Request

curl "https://api.basistheory.com/applications/fb124bba-f90d-45f0-9a59-5edca27b3b4a/regenerate" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED" \
  -X "POST"
import { BasisTheory } from '@basis-theory/basis-theory-js';

const bt = await new BasisTheory().init('key_N88mVGsp3sCXkykyN2EFED');

const application = await bt.applications.regenerateKey('fb124bba-f90d-45f0-9a59-5edca27b3b4a');
using BasisTheory.net.Applications;

var client = new ApplicationClient("key_N88mVGsp3sCXkykyN2EFED");

var application = await client.RegenerateKeyAsync("fb124bba-f90d-45f0-9a59-5edca27b3b4a");
# Coming Soon!

Response

{
  "id": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
  "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
  "name": "My Example App",
  "key": "key_FZ8RmaxoGc73lbmF2cpmUJ",
  "type": "server_to_server",
  "permissions": [
    "token:general:create",
    "token:general:read:low",
    "token:pci:create",
    "token:pci:read:low"
  ],
  "created_by": "c57a0d0d-e8e6-495f-9c79-a317cc21996c",
  "created_at": "2020-09-15T15:53:00+00:00",
  "modified_by": "a23699d2-1d55-4927-83f9-e76779f1c1c1",
  "modified_at": "2021-03-01T08:23:14+00:00"
}

POST https://api.basistheory.com/applications/{id}/regenerate

Regenerate the API key for an application.

Permissions

application:update

URI Parameters

Parameter Required Type Default Description
id true uuid null The ID of the application

Response

Returns an Application with the new key property populated. Returns an error if there were validation errors, or the application key failed to regenerate.

Delete Application

Request

curl "https://api.basistheory.com/applications/fb124bba-f90d-45f0-9a59-5edca27b3b4a" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED" \
  -X "DELETE"
import { BasisTheory } from '@basis-theory/basis-theory-js';

const bt = await new BasisTheory().init('key_N88mVGsp3sCXkykyN2EFED');

await bt.applications.delete('fb124bba-f90d-45f0-9a59-5edca27b3b4a');
using BasisTheory.net.Applications;

var client = new ApplicationClient("key_N88mVGsp3sCXkykyN2EFED");

await client.DeleteAsync("fb124bba-f90d-45f0-9a59-5edca27b3b4a");
# Coming Soon!

DELETE https://api.basistheory.com/applications/{id}

Delete an application by ID in the Tenant.

Permissions

application:delete

URI Parameters

Parameter Required Type Default Description
id true uuid null The ID of the application

Response

Returns an error if the application failed to delete.

Atomic Banks

Atomic Bank Object

Attribute Type Description
id uuid Unique identifier of the token which can be used to get an Atomic Bank
tenant_id uuid The Tenant ID which owns the bank
type string Bank token type
bank bank Bank data
fingerprint string Uniquely identifies this particular bank account. You can use this attribute to check whether two bank accounts are the same.
metadata map A key-value map of non-sensitive data.
created_by uuid (Optional) The Application ID which created the Atomic Bank
created_at date (Optional) Created date of the Atomic Bank in ISO 8601 format
modified_by uuid (Optional) The Application ID which last modified the Atomic Bank
modified_at date (Optional) Last modified date of the Atomic Bank in ISO 8601 format

Bank Object

Attribute Required Type Default Description
routing_number true string null Nine-digit ABA routing number
account_number true string null Account number up to seventeen-digits

Create Atomic Bank

Request

curl "https://api.basistheory.com/atomic/banks" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED" \
  -H "Content-Type: application/json" \
  -X "POST" \
  -d '{
      "bank": {
        "routing_number": "021000021",
        "account_number": "1234567890"
      },
      "metadata": {
        "nonSensitiveField": "Non-Sensitive Value"
      }
    }'
import { BasisTheory } from '@basis-theory/basis-theory-js';

const bt = await new BasisTheory().init('key_N88mVGsp3sCXkykyN2EFED');

const atomicBank = await bt.atomicBanks.create({
  bank: {
    routingNumber: '021000021',
    accountNumber: '1234567890',
  },
  metadata: {
    nonSensitiveField: 'Non-Sensitive Value'
  },
});
using BasisTheory.net.Atomic.Banks;

var client = new AtomicBankClient("key_N88mVGsp3sCXkykyN2EFED");

var atomicBank = await client.CreateAsync(new AtomicBank {
  Bank = new Bank {
    RoutingNumber = "021000021",
    AccountNumber = "1234567890"
  },
  Metadata = new Dictionary<string, string> {
    { "nonSensitiveField", "Non-Sensitive Value" }
  }
});
# Coming Soon!

Response

{
  "id": "1485efb9-6b1f-4248-a5d1-cf9b3907164c",
  "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
  "type": "bank",
  "bank": {
    "routing_number": "021000021",
    "account_number": "XXXXXX7890"
  },
  "fingerprint": "8j6WJgk4Dz1qoJgrHrioUFJhYKQTnk75DfJAue5bNab2",
  "metadata": {
    "nonSensitiveField": "Non-Sensitive Value"
  },
  "created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
  "created_at": "2020-09-15T15:53:00+00:00"
}

POST https://api.basistheory.com/atomic/banks

Create a new Atomic Bank for the Tenant.

Permissions

token:bank:create

Request Parameters

Attribute Required Type Default Description
bank true bank null Bank data
metadata false map null A key-value map of non-sensitive data.

Response

Returns an Atomic Bank with masked bank data if the Atomic Bank was created. Returns an error if there were validation errors, or the Atomic Bank failed to create.

List Atomic Banks

Request

curl "https://api.basistheory.com/atomic/banks" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED"
import { BasisTheory } from '@basis-theory/basis-theory-js';

const bt = await new BasisTheory().init('key_N88mVGsp3sCXkykyN2EFED');

const atomicBanks = await bt.atomicBanks.list();
using BasisTheory.net.Atomic.Banks;

var client = new AtomicBankClient("key_N88mVGsp3sCXkykyN2EFED");

var atomicBanks = await client.GetAsync();
# Coming Soon!

Response

{
  "pagination": {...}
  "data": [
    {
      "id": "1485efb9-6b1f-4248-a5d1-cf9b3907164c",
      "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
      "type": "bank",
      "bank": {
        "routing_number": "021000021",
        "account_number": "XXXXXX7890"
      },
      "fingerprint": "8j6WJgk4Dz1qoJgrHrioUFJhYKQTnk75DfJAue5bNab2",
      "metadata": {
        "nonSensitiveField": "Non-Sensitive Value"
      },
      "created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
      "created_at": "2020-09-15T15:53:00+00:00"
    },
    {...},
    {...}
  ]
}

GET https://api.basistheory.com/atomic/banks

Get a list of Atomic Banks for the Tenant.

Permissions

token:bank:read:<impact_level>

Response

Returns a paginated object with the data property containing an array of Atomic Banks. Providing any query parameters will filter the results. Plaintext Bank data will be returned when the requester has token:bank:read:high permission. Bank data will be masked when the requester has read permissions on bank classification at a lower impact level (i.e. token:bank:read:low, token:bank:read:moderate). Returns an error if Atomic Banks could not be retrieved.

Get an Atomic Bank

Request

curl "https://api.basistheory.com/atomic/banks/1485efb9-6b1f-4248-a5d1-cf9b3907164c" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED"
using BasisTheory.net.Atomic.Banks;

var client = new AtomicBankClient("key_N88mVGsp3sCXkykyN2EFED");

var atomicBank = await client.GetByIdAsync("1485efb9-6b1f-4248-a5d1-cf9b3907164c");
import { BasisTheory } from '@basis-theory/basis-theory-js';

const bt = await new BasisTheory().init('key_N88mVGsp3sCXkykyN2EFED');

const atomicBank = await bt.atomicBanks.retrieve('1485efb9-6b1f-4248-a5d1-cf9b3907164c');
# Coming Soon!

Response

{
  "id": "1485efb9-6b1f-4248-a5d1-cf9b3907164c",
  "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
  "type": "bank",
  "bank": {
    "routing_number": "021000021",
    "account_number": "XXXXXX7890"
  },
  "fingerprint": "8j6WJgk4Dz1qoJgrHrioUFJhYKQTnk75DfJAue5bNab2",
  "metadata": {
    "nonSensitiveField": "Non-Sensitive Value"
  },
  "created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
  "created_at": "2020-09-15T15:53:00+00:00"
}

GET https://api.basistheory.com/atomic/banks/{id}

Get an Atomic Bank by ID in the Tenant.

Permissions

token:bank:read:<impact_level>

URI Parameters

Parameter Required Type Default Description
id true uuid null The ID of the Atomic Bank

Response

Returns an Atomic Bank with the id provided. Plaintext Bank data will be returned when the requester has token:bank:read:high permission. Bank data will be masked when the requester has read permissions on bank classification at a lower impact level (i.e. token:bank:read:low, token:bank:read:moderate). Returns an error if the Atomic Bank could not be retrieved.

Update Atomic Bank

Request

curl "https://api.basistheory.com/atomic/banks/1485efb9-6b1f-4248-a5d1-cf9b3907164c" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED" \
  -H "Content-Type: application/json" \
  -X "PATCH" \
  -d '{
      "bank": {
        "routing_number": "021000021",
        "account_number": "1234567890"
      },
    }'
import { BasisTheory } from '@basis-theory/basis-theory-js';

const bt = await new BasisTheory().init('key_N88mVGsp3sCXkykyN2EFED');

const atomicBank = await bt.atomicBanks.update("1485efb9-6b1f-4248-a5d1-cf9b3907164c", {
  bank: {
    routingNumber: '021000021',
    accountNumber: '1234567890',
  },
});
using BasisTheory.net.Atomic.Banks;

var client = new AtomicBankClient("key_N88mVGsp3sCXkykyN2EFED");

var atomicBank = await client.UpdateAsync("1485efb9-6b1f-4248-a5d1-cf9b3907164c", new UpdateAtomicBankRequest {
  Bank = new Bank {
    RoutingNumber = "021000021",
    AccountNumber = "1234567890"
  },
});
# Coming Soon!

Response

{
  "id": "1485efb9-6b1f-4248-a5d1-cf9b3907164c",
  "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
  "type": "bank",
  "bank": {
    "routing_number": "021000021",
    "account_number": "XXXXXX7890"
  },
  "fingerprint": "8j6WJgk4Dz1qoJgrHrioUFJhYKQTnk75DfJAue5bNab2",
  "metadata": {
    "nonSensitiveField": "Non-Sensitive Value"
  },
  "created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
  "created_at": "2020-09-15T15:53:00+00:00",
  "modified_by": "34053374-d721-43d8-921c-5ee1d337ef21",
  "modified_at": "2021-10-27T17:34:23+00:00"
}

PATCH https://api.basistheory.com/atomic/banks/{id}

Update an Atomic Bank for the Tenant. At least one property on the request body is required.

Permissions

token:bank:update

Request Parameters

Attribute Required Type Default Description
bank true bank null Bank data

Response

Returns an Atomic Bank with masked bank data if the Atomic Bank was updated. Returns an error if there were validation errors, or the Atomic Bank failed to update.

Delete Atomic Bank

Request

curl "https://api.basistheory.com/atomic/banks/1485efb9-6b1f-4248-a5d1-cf9b3907164c" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED" \
  -X "DELETE"
import { BasisTheory } from '@basis-theory/basis-theory-js';

const bt = await new BasisTheory().init('key_N88mVGsp3sCXkykyN2EFED');

await bt.atomicBanks.delete('1485efb9-6b1f-4248-a5d1-cf9b3907164c');
using BasisTheory.net.Atomic.Banks;

var client = new AtomicBankClient("key_N88mVGsp3sCXkykyN2EFED");

await client.DeleteAsync("1485efb9-6b1f-4248-a5d1-cf9b3907164c");
# Coming Soon!

DELETE https://api.basistheory.com/atomic/banks/{id}

Delete an Atomic Bank by ID in the Tenant.

Permissions

token:bank:delete

URI Parameters

Parameter Required Type Default Description
id true uuid null The ID of the Atomic Bank

Response

Returns an error if the Atomic Bank failed to delete.

Decrypt Atomic Bank DEPRECATED

Request

curl "https://api.basistheory.com/atomic/banks/1485efb9-6b1f-4248-a5d1-cf9b3907164c/decrypt" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED"
import { BasisTheory } from '@basis-theory/basis-theory-js';

const bt = await new BasisTheory().init('key_N88mVGsp3sCXkykyN2EFED');

const atomicBank = await bt.atomicBanks.retrieveDecrypted('1485efb9-6b1f-4248-a5d1-cf9b3907164c');
using BasisTheory.net.Atomic.Banks;

var client = new AtomicBankClient("key_N88mVGsp3sCXkykyN2EFED");

var atomicBank = await client.GetByIdAsync("1485efb9-6b1f-4248-a5d1-cf9b3907164c", 
  new BankGetByIdRequest {
    Decrypt = true
  });
# Coming Soon!

Response

{
  "id": "1485efb9-6b1f-4248-a5d1-cf9b3907164c",
  "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
  "type": "bank",
  "bank": {
    "routing_number": "021000021",
    "account_number": "1234567890"
  },
  "fingerprint": "8j6WJgk4Dz1qoJgrHrioUFJhYKQTnk75DfJAue5bNab2",
  "metadata": {
    "nonSensitiveField": "Non-Sensitive Value"
  },
  "created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
  "created_at": "2020-09-15T15:53:00+00:00"
}

GET https://api.basistheory.com/atomic/banks/{id}/decrypt

Decrypt an Atomic Bank by ID in the Tenant.

Permissions

token:bank:read:high

URI Parameters

Parameter Required Type Default Description
id true uuid null The ID of the Atomic Bank

Response

Returns an Atomic Bank with plaintext bank data with the id provided. Returns an error if the Atomic Bank could not be retrieved.

React with an Atomic Bank

Request

curl "https://api.basistheory.com/atomic/banks/1485efb9-6b1f-4248-a5d1-cf9b3907164c/react" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED" \
  -X "POST" \
  -d '{
    "reactor_id": "5b493235-6917-4307-906a-2cd6f1a90b13",
    "request_parameters": {
      "REQUEST_PARAMETER_1": "Some request value"
    },
    "metadata": {
      "nonSensitiveField": "Non-Sensitive Value"
    }
  }'
import { BasisTheory } from '@basis-theory/basis-theory-js';

const bt = await new BasisTheory().init('key_N88mVGsp3sCXkykyN2EFED');

const reactResponse = await bt.atomicBanks.react('1485efb9-6b1f-4248-a5d1-cf9b3907164c', {
  reactorId: '5b493235-6917-4307-906a-2cd6f1a90b13',
  requestParameters: {
    REQUEST_PARAMETER_1: 'Some request value',
  },
  metadata: {
    nonSensitiveField: 'Non-Sensitive value',
  },
});
using BasisTheory.net.Atomic.Banks;

var client = new AtomicBankClient("key_N88mVGsp3sCXkykyN2EFED");

var reactResponse = await client.ReactAsync("1485efb9-6b1f-4248-a5d1-cf9b3907164c", 
  new ReactRequest {
    ReactorId = "5b493235-6917-4307-906a-2cd6f1a90b13",
    RequestParameters = new Dictionary<string, object> {
      { "REQUEST_PARAMETER_1",  "Some request value" }
    },
    Metadata = new Dictionary<string, string> {
      { "nonSensitiveField",  "Non-Sensitive Value" }
    }
  });
# Coming Soon!

POST https://api.basistheory.com/atomic/banks/{id}/react

React with an Atomic Bank by ID.

Permissions

token:bank:use:reactor

URI Parameters

Parameter Required Type Default Description
id true uuid null The ID of the Atomic Bank

Request Parameters

Parameter Required Type Default Description
reactor_id true uuid null The ID of the reactor
request_parameters false map null A key-value map of request parameters names and values for the reactor
metadata false map null A key-value map of non-sensitive data. We overwrite the following keys: correlation_id, reactor_id, reactor_name, source_token_id, and source_token_type

Response

Returns a React Response if the Atomic Bank was reacted successfully. Returns an error if the Atomic Bank failed to react. Errors generated from Reactors will be translated to the common Basis Theory Error format. See Reactor Errors for more details.

React Response Object

Attribute Type Description
tokens map (Optional) Token(s) created from the tokenize block of the Reactor response
raw map (Optional) Raw output returned from the Reactor

Test Banks

To enable testing of Atomic Banks, we've implemented a list of acceptable test bank accounts to ensure you are able to test with non-sensitive data.

Test bank accounts

Routing Number Account Number Description
110000000 000123456789 Successfully added bank

Atomic Cards

Atomic Card Object

Attribute Type Description
id uuid Unique identifier of the token which can be used to get an Atomic Card
tenant_id uuid The Tenant ID which owns the card
type string Card token type
card card Card data
fingerprint string Uniquely identifies this particular card number. You can use this attribute to check whether two card tokens contain the same card number.
metadata map A key-value map of non-sensitive data.
created_by uuid (Optional) The Application ID which created the Atomic Card
created_at date (Optional) Created date of the Atomic Card in ISO 8601 format
modified_by uuid (Optional) The Application ID which last modified the Atomic Card
modified_at date (Optional) Last modified date of the Atomic Card in ISO 8601 format

Card Object

Attribute Required Type Default Description
number true string null The card number without any separators
expiration_month false integer null Two-digit number representing the card's expiration month
expiration_year false integer null Four-digit number representing the card's expiration year
cvc false string null Three or four-digit card verification code

Create Atomic Card

Request

curl "https://api.basistheory.com/atomic/cards" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED" \
  -H "Content-Type: application/json" \
  -X "POST" \
  -d '{
    "card": {
      "number": "4242424242424242",
      "expiration_month": 12,
      "expiration_year": 2025,
      "cvc": "123"
    },
    "metadata": {
      "nonSensitiveField": "Non-Sensitive Value"
    }
  }'
import { BasisTheory } from '@basis-theory/basis-theory-js';

const bt = await new BasisTheory().init('key_N88mVGsp3sCXkykyN2EFED');

const atomicCard = await bt.atomicCards.create({
  card: {
    number: '4242424242424242',
    expirationMonth: 12,
    expirationYear: 2025,
    cvc: '123',
  },
  metadata: {
    nonSensitiveField: 'Non-Sensitive Value'
  },
});
using BasisTheory.net.Atomic.Cards;

var client = new AtomicCardClient("key_N88mVGsp3sCXkykyN2EFED");

var atomicCard = await client.CreateAsync(new AtomicCard {
  Card = new Card {
    CardNumber = "4242424242424242",
    ExpirationMonth = 12,
    ExpirationYear = 2025,
    CardVerificationCode = "123"
  },
  Metadata = new Dictionary<string, string> {
    { "nonSensitiveField", "Non-Sensitive Value" }
  }
});
# Coming Soon!

Response

{
  "id": "c1e565009-1984-4638-8fca-dce8a82cc2af",
  "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
  "type": "card",
  "card": {
    "number": "XXXXXXXXXXXX4242",
    "expiration_month": 12,
    "expiration_year": 2025
  },
  "fingerprint": "EVYsSLRyb86Z5awJksvnjVMEC4iP7KX639GtHVUFpzER",
  "metadata": {
    "nonSensitiveField": "Non-Sensitive Value"
  },
  "created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
  "created_at": "2020-09-15T15:53:00+00:00",
  "modified_by": "34053374-d721-43d8-921c-5ee1d337ef21",
  "modified_at": "2021-10-27T17:34:23+00:00"
}

POST https://api.basistheory.com/atomic/cards

Create a new Atomic Card for the Tenant.

Permissions

token:pci:create

Request Parameters

Attribute Required Type Default Description
card true card null Card data
metadata false map null A key-value map of non-sensitive data.

Response

Returns an Atomic Card with masked card data if the Atomic Card was created. Returns an error if there were validation errors, or the Atomic Card failed to create.

List Atomic Cards

Request

curl "https://api.basistheory.com/atomic/cards" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED"
import { BasisTheory } from '@basis-theory/basis-theory-js';

const bt = await new BasisTheory().init('key_N88mVGsp3sCXkykyN2EFED');

const atomicCards = await bt.atomicCards.list();
using BasisTheory.net.Atomic.Cards;

var client = new AtomicCardClient("key_N88mVGsp3sCXkykyN2EFED");

var atomicCards = await client.GetAsync();
# Coming Soon!

Response

{
  "pagination": {...}
  "data": [
    {
      "id": "c1e565009-1984-4638-8fca-dce8a82cc2af",
      "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
      "type": "card",
      "card": {
        "number": "XXXXXXXXXXXX4242",
        "expiration_month": 12,
        "expiration_year": 2025
      },
      "fingerprint": "EVYsSLRyb86Z5awJksvnjVMEC4iP7KX639GtHVUFpzER",
      "metadata": {
        "nonSensitiveField": "Non-Sensitive Value"
      },
      "created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
      "created_at": "2020-09-15T15:53:00+00:00"
    },
    {...},
    {...}
  ]
}

GET https://api.basistheory.com/atomic/cards

Get a list of Atomic Cards for the Tenant.

Permissions

token:pci:read:<impact_level>

Response

Returns a paginated object with the data property containing an array of Atomic Cards. Providing any query parameters will filter the results. Returns an error if Atomic Cards could not be retrieved.

Get an Atomic Card

Request

curl "https://api.basistheory.com/atomic/cards/c1e565009-1984-4638-8fca-dce8a82cc2af" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED"
import { BasisTheory } from '@basis-theory/basis-theory-js';

const bt = await new BasisTheory().init('key_N88mVGsp3sCXkykyN2EFED');

const atomicCard = await bt.atomicCards.retrieve('c1e565009-1984-4638-8fca-dce8a82cc2af');
using BasisTheory.net.Atomic.Cards;

var client = new AtomicCardClient("key_N88mVGsp3sCXkykyN2EFED");

var atomicCard = await client.GetByIdAsync("c1e565009-1984-4638-8fca-dce8a82cc2af");
# Coming Soon!

Response

{
  "id": "c1e565009-1984-4638-8fca-dce8a82cc2af",
  "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
  "type": "card",
  "card": {
    "number": "XXXXXXXXXXXX4242",
    "expiration_month": 12,
    "expiration_year": 2025
  },
  "fingerprint": "EVYsSLRyb86Z5awJksvnjVMEC4iP7KX639GtHVUFpzER",
  "metadata": {
    "nonSensitiveField": "Non-Sensitive Value"
  },
  "created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
  "created_at": "2020-09-15T15:53:00+00:00"
}

GET https://api.basistheory.com/atomic/cards/{id}

Get an Atomic Card by ID in the Tenant.

Permissions

token:pci:read:<impact_level>

URI Parameters

Parameter Required Type Default Description
id true uuid null The ID of the Atomic Card

Response

Returns an Atomic Card with the id provided. Returns an error if the Atomic Card could not be retrieved.

Update Atomic Card

Request

curl "https://api.basistheory.com/atomic/cards/c1e565009-1984-4638-8fca-dce8a82cc2af" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED" \
  -H "Content-Type: application/json" \
  -X "PATCH" \
  -d '{
    "card": {
      "number": "4242424242424242",
      "expiration_month": 12,
      "expiration_year": 2025,
      "cvc": "123"
    }
  }'
import { BasisTheory } from '@basis-theory/basis-theory-js';

const bt = await new BasisTheory().init('key_N88mVGsp3sCXkykyN2EFED');

const atomicCard = await bt.atomicCards.update("c1e565009-1984-4638-8fca-dce8a82cc2af", {
  card: {
    number: '4242424242424242',
    expirationMonth: 12,
    expirationYear: 2025,
    cvc: '123',
  }
});
using BasisTheory.net.Atomic.Cards;

var client = new AtomicCardClient("key_N88mVGsp3sCXkykyN2EFED");

var atomicCard = await client.UpdateAsync("c1e565009-1984-4638-8fca-dce8a82cc2af", new UpdateAtomicCardRequest {
  Card = new Card {
    CardNumber = "4242424242424242",
    ExpirationMonth = 12,
    ExpirationYear = 2025,
    CardVerificationCode = "123"
  }
});
# Coming Soon!

Response

{
  "id": "c1e565009-1984-4638-8fca-dce8a82cc2af",
  "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
  "type": "card",
  "card": {
    "number": "XXXXXXXXXXXX4242",
    "expiration_month": 12,
    "expiration_year": 2025
  },
  "fingerprint": "EVYsSLRyb86Z5awJksvnjVMEC4iP7KX639GtHVUFpzER",
  "metadata": {
    "nonSensitiveField": "Non-Sensitive Value"
  },
  "created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
  "created_at": "2020-09-15T15:53:00+00:00",
  "modified_by": "34053374-d721-43d8-921c-5ee1d337ef21",
  "modified_at": "2021-10-27T17:34:23+00:00"
}

PATCH https://api.basistheory.com/atomic/cards/{id}

Update an Atomic Card for the Tenant. At least one property on the request body is required.

Permissions

token:pci:update

Request Parameters

Attribute Required Type Default Description
card false card null Card data

Response

Returns an Atomic Card with masked card data if the Atomic Card was updated. Returns an error if there were validation errors, or the Atomic Card failed to update.

Delete Atomic Card

Request

curl "https://api.basistheory.com/atomic/cards/c1e565009-1984-4638-8fca-dce8a82cc2af" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED" \
  -X "DELETE"
import { BasisTheory } from '@basis-theory/basis-theory-js';

const bt = await new BasisTheory().init('key_N88mVGsp3sCXkykyN2EFED');

await bt.atomicCards.delete('c1e565009-1984-4638-8fca-dce8a82cc2af');
using BasisTheory.net.Atomic.Cards;

var client = new AtomicCardClient("key_N88mVGsp3sCXkykyN2EFED");

await client.DeleteAsync("c1e565009-1984-4638-8fca-dce8a82cc2af");
# Coming Soon!

DELETE https://api.basistheory.com/atomic/cards/{id}

Delete an Atomic Card by ID in the Tenant.

Permissions

token:pci:delete

URI Parameters

Parameter Required Type Default Description
id true uuid null The ID of the Atomic Card

Response

Returns an error if the Atomic Card failed to delete.

React with an Atomic Card

Request

curl "https://api.basistheory.com/atomic/cards/c1e565009-1984-4638-8fca-dce8a82cc2af/react" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED" \
  -X "POST" \
  -d '{
    "reactor_id": "5b493235-6917-4307-906a-2cd6f1a90b13",
    "request_parameters": {
      "REQUEST_PARAMETER_1": "Some request value"
    },
    "metadata": {
      "nonSensitiveField": "Non-Sensitive Value"
    }
  }'
import { BasisTheory } from '@basis-theory/basis-theory-js';

const bt = await new BasisTheory().init('key_N88mVGsp3sCXkykyN2EFED');

const reactResponse = await bt.atomicCards.react('c1e565009-1984-4638-8fca-dce8a82cc2af', {
  reactorId: '5b493235-6917-4307-906a-2cd6f1a90b13',
  requestParameters: {
    REQUEST_PARAMETER_1: 'Some request value',
  },
  metadata: {
    nonSensitiveField: 'Non-Sensitive Value',
  },
});
using BasisTheory.net.Atomic.Cards;

var client = new AtomicCardClient("key_N88mVGsp3sCXkykyN2EFED");

var reactResponse = await client.ReactAsync("c1e565009-1984-4638-8fca-dce8a82cc2af", 
  new ReactRequest {
    ReactorId = "5b493235-6917-4307-906a-2cd6f1a90b13",
    RequestParameters = new Dictionary<string, object> {
      { "REQUEST_PARAMETER_1",  "Some request value" }
    },
    Metadata = new Dictionary<string, string> {
      { "nonSensitiveField",  "Non-Sensitive Value" }
    }
  });
# Coming Soon!

POST https://api.basistheory.com/atomic/cards/{id}/react

React with an Atomic Card by ID.

Permissions

token:pci:use:reactor

URI Parameters

Parameter Required Type Default Description
id true uuid null The ID of the Atomic Card

Request Parameters

Parameter Required Type Default Description
reactor_id true uuid null The ID of the reactor
request_parameters false map null A key-value map of request parameters names and values for the reactor
metadata false map null A key-value map of non-sensitive data. We overwrite the following keys: correlation_id, reactor_id, reactor_name, source_token_id, and source_token_type

Response

Returns a React Response if the Atomic Card was reacted successfully. Returns an error if the Atomic Card failed to react. Errors generated from Reactors will be translated to the common Basis Theory Error format. See Reactor Errors for more details.

React Response Object

Attribute Type Description
tokens map (Optional) Token(s) created from the tokenize block of the Reactor response
raw map (Optional) Raw output returned from the Reactor

Test Cards

To enable testing of Atomic Cards, we've implemented a list of acceptable test card numbers to ensure you are able to test with non-sensitive data.

Test card numbers

Card Description
4242424242424242 Test card
4000056655665556 Test card
5555555555554444 Test card
2223003122003222 Test card
5200828282828210 Test card
5105105105105100 Test card
378282246310005 Test card
371449635398431 Test card
6011111111111117 Test card
6011000990139424 Test card
3056930009020004 Test card
36227206271667 Test card
3566002020360505 Test card
620000000000000 Test card

Logs

Log Object

Attribute Type Description
tenant_id uuid The Tenant ID which owns the entity
actor_id uuid (Optional) The ID of the actor which performed the operation
actor_type string (Optional) The type of actor which performed the operation (e.g. "user", "application")
entity_type string The entity type of the log
entity_id string The unique identifier of the entity_type
operation string The log operation (e.g. create, update, read, delete)
message string The log message
created_at date Created date of the token in ISO 8601 format

List Logs

Request

curl "https://api.basistheory.com/logs" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED"
import { BasisTheory } from '@basis-theory/basis-theory-js';

const bt = await new BasisTheory().init('key_N88mVGsp3sCXkykyN2EFED');

const logs = await bt.logs.list();
using BasisTheory.net.Logs;

var client = new LogClient("key_N88mVGsp3sCXkykyN2EFED");

var logs = await client.GetAsync();
# Coming Soon!

Response

{
  "pagination": {...},
  "data": [
    {
      "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
      "actor_id": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
      "actor_type": "application",
      "entity_type": "token",
      "entity_id": "c06d0789-0a38-40be-b7cc-c28a718f76f1",
      "operation": "read",
      "message": "Token retrieved",
      "created_at": "2021-03-01T08:23:14+00:00"
    },
    {...},
    {...}
  ]
}

GET https://api.basistheory.com/logs

Get a list of logs for the Tenant.

Permissions

log:read

Query Parameters

Parameter Required Type Default Description
entity_type false string null An optional entity type to filter the list of logs by. (e.g. card, bank, application, tenant)
entity_id false string null The unique identifier of the entity_type to filter the list of logs by.
start_date false date null An ISO 8601 formatted date to filter logs where created_at is greater than or equal to
end_date false date null An ISO 8601 formatted date to filter logs where created_at is less than

Response

Returns a paginated object with the data property containing an array of logs. Providing any query parameters will filter the results. Returns an error if logs could not be retrieved.

Permissions

Permissions offer fine-grained control over your Application's access to different aspects of your token infrastructure. We suggest limiting the scope of your Application to the least amount possible, and to not share them across your internal services.

Permissions are associated with every Application and can be configured when you create an Application or update an Application.

Every API endpoint will document the required permissions needed to perform the operation against the endpoint.

Permission Object

Attribute Type Description
type string Permission type referenced by Basis Theory API endpoints
description string Description of the permission
application_types array List of application types that can assign the permission

Permission Types

Management Permissions

Permission Description Application Types
tenant:read Read Tenants management
tenant:update Update Tenants management
tenant:delete Delete Tenants management
application:read Read Applications management
application:create Create Applications management
application:update Update and regenerate API keys for Applications management
application:delete Delete Applications management
reactor:read Read Reactor Formulas and Reactors management
reactor:create Create Reactors Formulas and Reactors management
reactor:update Update Reactors Formulas and Reactors management
reactor:delete Delete Reactors Formulas and Reactors management
log:read Read audit logs management

Token Permissions

All Token permissions follow the form of token:<classification>:<operation>:<scope?>.

Permission Description Application Types
token:<classification>:create Create Tokens in <classification> (e.g. token:general:create) public, elements, server_to_server
token:<classification>:read:low Read plaintext token data in <classification> with low <impact_level>. Tokens in <classification> with higher impact level will be restricted based on the token's restriction policy server_to_server
token:<classification>:read:moderate Read plaintext token data in <classification> with moderate <impact_level> and lower. Tokens in <classification> with higher impact level will be restricted based on the token's restriction policy server_to_server
token:<classification>:read:high Read plaintext token data in <classification> with high <impact_level> and lower (i.e. low and moderate). server_to_server
token:<classification>:update Update Tokens in <classification> (e.g. token:general:update) server_to_server
token:<classification>:delete Delete Tokens in <classification> (e.g. token:general:delete) server_to_server
token:<classification>:use:proxy Use Tokens in <classification> via Proxy (e.g. token:general:use:proxy) server_to_server
token:<classification>:use:reactor Use Tokens in <classification> via Reactor (e.g. token:general:use:reactor) server_to_server

List Permissions

Request

curl "https://api.basistheory.com/permissions" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED"
import {BasisTheory} from '@basis-theory/basis-theory-js';

const bt = await new BasisTheory().init('key_N88mVGsp3sCXkykyN2EFED');

const permissions = await bt.permissions.list();
using BasisTheory.net.Permissions;

var client = new PermissionClient("key_N88mVGsp3sCXkykyN2EFED");

var permissions = await client.GetAsync();
# Coming Soon!

Response

[
  {
    "type": "token:pci:read:low",
    "description": "Read tokens with PCI classification of low impact level",
    "application_types": [
      "server_to_server"
    ]
  },
  {...},
  {...}
]

GET https://api.basistheory.com/permissions

Response

Returns an array of permission objects. Returns an error if permissions could not be retrieved.

Proxy BETA

Proxying Outbound Requests

The Basis Theory Proxy provides a simple mechanism to use the data you've stored with Basis Theory in outbound requests to a third party API. Basis Theory token identifiers included in the request will be replaced with the raw token data and then the modified request will be forwarded to the destination specified in the BT-PROXY-URL request header. The destination will receive the raw data in the request without your system needing to interact with sensitive data on your own servers.

Proxy Requests

Request

curl "https://api.basistheory.com/proxy" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED" \
  -H "BT-PROXY-URL: https://example.com/api" \
  -X "POST" \
  -d '{
    "parameter1": "{{26818785-547b-4b28-b0fa-531377e99f4e}}",
    "parameter2": "non-interpolated"
  }'

POST https://api.basistheory.com/proxy

PUT https://api.basistheory.com/proxy

PATCH https://api.basistheory.com/proxy

DELETE https://api.basistheory.com/proxy

GET https://api.basistheory.com/proxy

Proxy a request to a third party API.

Authentication

Proxy requests must be authenticated using an BT-API-KEY header (see Authentication).

Permissions

Depending on the classification(s) of Tokens you need to forward to a third party, the corresponding token:<classification>:use:proxy permission is required. At least one token:<classification>:use:proxy permission is required, for example:

token:general:use:proxy token:pci:use:proxy token:bank:use:proxy

Configuration

Proxy requests require a BT-PROXY-URL request header to be set. The value of the BT-PROXY-URL header defines the base URL to which the request will be proxied. The BT-PROXY-URL request header must use HTTPS with DNS as the host. Destinations must use HTTPS >= TLSv1.2 over port 443.

The BT-PROXY-URL request header will serve as the base URL for the proxied request. Any path and/or query parameters under /proxy/** will be appended to the base URL before forwarding the request.

For example, sending a proxy request to https://api.basistheory.com/proxy/foo/bar?param=value and including the header BT-PROXY-URL=https://example.com/api will result in the request being forwarded to https://example.com/api/foo/bar?param=value.

Detokenization

The Basis Theory Proxy will attempt to detokenize certain interpolation patterns and inject the raw token data in the request body before sending the request to the downstream destination.

The proxy will substitute any patterns of the form {{tokenId}} within the request with the raw token data represented by that tokenId. For example, given a token:

{
    "id": "26818785-547b-4b28-b0fa-531377e99f4e",
    "data": "sensitive data"
}

and a proxy request with the body:

{
    "parameter1": "{{26818785-547b-4b28-b0fa-531377e99f4e}}",
    "parameter2": "non-interpolated"
}

then the following request body will sent to the desintation:

{
    "parameter1": "senstive data",
    "parameter2": "non-interpolated"
}

Requests may contain a mixture of both token interpolation patterns and non-interpolated raw data. The token:<classification>:use:proxy permission is required in order to detokenize tokens classified as <classification> within a proxy request. At most, 100 unique tokens may be detokenized within a single proxy request.

Proxy Responses

Unless an error occurs within the Basis Theory Proxy, the raw response from the destination will be returned from the proxy.

If an error occurs within the proxy (eg. missing or invalid BT-PROXY-URL header), then the following error response will be returned:

Attribute Type Description
proxy_error any A standard Basis Theory error

Reactor Formulas

Reactor formulas give you the ability to pre-configure custom integrations to securely process, enrich, and associate your tokens.

Reactor Formula Object

Attribute Type Description
id uuid Unique identifier of the Reactor Formula which can be used to get a Reactor Formula
name string The name of the Reactor Formula. Has a maximum length of 200
description string The description of the Reactor Formula
type string Type of the Reactor Formula
source_token_type string Source token type of the Reactor Formula
icon string Base64 data URL of the image
code string Reactor Formula code which will be executed when the Reactor Formula is processed
configuration array Array of configuration options for configuring a reactor
request_parameters array Array of request parameters which will be passed when executing the reactor
created_at date (Optional) Created date of the Reactor Formula in ISO 8601 format
created_by uuid (Optional) The ID of the user or Application that created the Reactor Formula
modified_at date (Optional) Last modified date of the Reactor Formula in ISO 8601 format
modified_by uuid (Optional) The ID of the user or Application that last modified the Reactor Formula

Reactor Formula Configuration Object

Attribute Required Type Default Description
name true string null Name of the configuration setting
description false string null Description of the configuration setting
type true string null Data type of the configuration setting. Valid values are string, boolean, and number

Reactor Formula Request Parameter Object

Attribute Required Type Default Description
name true string null Name of the request parameter
description false string null Description of the request parameter
type true string null Data type of the request parameter. Valid values are string, boolean, and number
optional false boolean false If the request parameter is optional when executing the reactor

Reactor Formula Code

All Reactor Formula code snippets must export a function which takes in a context object and returns a token object.

Reactor Formula Code Context Object

Attribute Type Description
sourceToken object The source token that matches the source_token_type of the reactor-formula
configuration array The configuration defined for the Reactor object

Reactor Formula Types

Type Description
official Official formulas that are built and supported by Basis Theory and its authorized partners
private Private formulas which are only available to your Tenant

Create Reactor Formula BETA

Request

curl "https://api.basistheory.com/reactor-formulas" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED" \
  -H "Content-Type: application/json" \
  -X "POST" \
  -d '{
    "name": "My Private Reactor",
    "description": "Securely react a token for another token",
    "type": "private",
    "source_token_type": "card",
    "icon": "data:image/png;base64, iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==",
    "code": "
      module.exports = async function (context) {
        // Do something with `context.configuration.SERVICE_API_KEY`

        return {
          foo: 'bar',
        };
      };
    ",
    "configuration": [
      {
        "name": "SERVICE_API_KEY",
        "description": "Configuration description",
        "type": "string"
      }
    ],
    "request_parameters": [
      {
        "name": "REQUEST_PARAMETER_1",
        "description": "Request parameter description",
        "type": "string"
      },
      {
        "name": "REQUEST_PARAMETER_2",
        "description": "Request parameter description",
        "type": "boolean",
        "optional": true
      }
    ]
  }'
import { BasisTheory } from '@basis-theory/basis-theory-js';

const bt = await new BasisTheory().init('key_N88mVGsp3sCXkykyN2EFED');

const reactorFormula = await bt.reactorFormulas.create({
  name: 'My Private Reactor',
  description: 'Securely exchange token for another token',
  type: 'private',
  sourceTokenType: 'card',
  icon: 'data:image/png;base64, iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==',
  code: '
    module.exports = async function (context) {
      // Do something with `context.configuration.SERVICE_API_KEY`

      return {
        foo: 'bar',
      };
    };
  ',
  configuration: [
    {
      name: 'SERVICE_API_KEY',
      description: 'Configuration description',
      type: 'string',
    },
  ],
  requestParameters: [
    {
      name: 'REQUEST_PARAMETER_1',
      description: 'Request parameter description',
      type: 'string',
    },
    {
      name: 'REQUEST_PARAMETER_2',
      description: 'Request parameter description',
      type: 'boolean',
      optional: true
    }
  ],
});
using BasisTheory.net.ReactorFormulas;

var client = new ReactorFormulaClient("key_N88mVGsp3sCXkykyN2EFED");

var reactorFormula = await client.CreateAsync(new ReactorFormula {
  Name = "My Private Reactor",
  Description = "Securely exchange token for another token",
  Type = "private",
  SourceTokenType = "card",
  Icon = "data:image/png;base64, iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==",
  Code = @"
    module.exports = async function (context) {
      // Do something with `context.configuration.SERVICE_API_KEY`

      return {
        foo: 'bar',
      };
    };
  ",
  Configuration = new List<ReactorFormulaConfiguration> {
    new ReactorFormulaConfiguration {
      Name = "SERVICE_API_KEY",
      Description = "Configuration description",
      Type = "string"
    }
  },
  RequestParameters = new List<ReactorFormulaRequestParameter> {
    new ReactorFormulaRequestParameter {
      Name = "REQUEST_PARAMETER_1",
      Description = "Request parameter description",
      Type = "string"
    },
    new ReactorFormulaRequestParameter {
      Name = "REQUEST_PARAMETER_2",
      Description = "Request parameter description",
      Type = "boolean",
      IsOptional = true
    }
  }
});
# Coming Soon!

Response

{
  "id": "17069df1-80f4-439e-86a7-4121863e4678",
  "name": "My Private Reactor",
  "description": "Securely exchange token for another token",
  "type": "private",
  "source_token_type": "card",
  "icon": "data:image/png;base64, iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==",
  "code": "
    module.exports = async function (context) {
      // Do something with `context.configuration.SERVICE_API_KEY`

      return {
        data: {
          foo: 'bar',
        },
        metadata: {
          nonSensitiveField: 'Non-Sensitive Value'
        }
      };
    };
  ",
  "configuration": [
    {
      "name": "SERVICE_API_KEY",
      "description": "Configuration description",
      "type": "string"
    }
  ],
  "request_parameters": [
    {
      "name": "REQUEST_PARAMETER_1",
      "description": "Request parameter description",
      "type": "string"
    },
    {
      "name": "REQUEST_PARAMETER_2",
      "description": "Request parameter description",
      "type": "boolean",
      "optional": true
    }
  ],
  "created_by": "c57a0d0d-e8e6-495f-9c79-a317cc21996c",
  "created_at": "2020-09-15T15:53:00+00:00"
}

POST https://api.basistheory.com/reactor-formulas

Create a new Reactor Formula for the Tenant.

Permissions

reactor:create

Request Parameters

Attribute Required Type Default Description
name true string null The name of the Reactor Formula. Has a maximum length of 200
description false string null The description of the Reactor Formula
type true string null Type of the Reactor Formula
source_token_type true string null Source token type of the Reactor Formula
icon false string null Base64 data URL of the image. Supported image types are: image/png, image/jpg, and image/jpeg
code true string null Reactor code which will be executed when the Reactor Formula is processed
configuration true array [] Array of configuration options for configuring a Reactor
request_parameters true array [] Array of request parameters which will be passed when executing the Reactor

Response

Returns an Reactor Formula if the Reactor Formula was created. Returns an error if there were validation errors, or the Reactor Formula failed to create.

List Reactor Formulas

Request

curl "https://api.basistheory.com/reactor-formulas" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED"
import { BasisTheory } from '@basis-theory/basis-theory-js';

const bt = await new BasisTheory().init('key_N88mVGsp3sCXkykyN2EFED');

const reactorFormulas = await bt.reactorFormulas.list();
using BasisTheory.net.ReactorFormulas;

var client = new ReactorFormulaClient("key_N88mVGsp3sCXkykyN2EFED");

var reactorFormulas = await client.GetAsync();
# Coming Soon!

Response

{
  "pagination": {...}
  "data": [
    {
      "id": "17069df1-80f4-439e-86a7-4121863e4678",
      "name": "My Private Reactor",
      "description": "Securely exchange token for another token",
      "type": "private",
      "source_token_type": "card",
      "icon": "data:image/png;base64, iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==",
      "code": "
        module.exports = async function (context) {
          // Do something with `context.configuration.SERVICE_API_KEY`

          return {
            data: {
              foo: 'bar',
            },
            metadata: {
              nonSensitiveField: 'Non-Sensitive Value'
            }
          };
        };
      ",
      "configuration": [
        {
          "name": "SERVICE_API_KEY",
          "description": "Configuration description",
          "type": "string"
        }
      ],
      "request_parameters": [
        {
          "name": "REQUEST_PARAMETER_1",
          "description": "Request parameter description",
          "type": "string"
        },
        {
          "name": "REQUEST_PARAMETER_2",
          "description": "Request parameter description",
          "type": "boolean",
          "optional": true
        }
      ],
      "created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
      "created_at": "2020-09-15T15:53:00+00:00",
      "modified_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
      "modified_at": "2021-03-01T08:23:14+00:00"
    },
    {...},
    {...}
  ]
}

GET https://api.basistheory.com/reactor-formulas

Get a list of official Reactor Formula and private, Tenant-specific Reactor Formulas.

Permissions

reactor:read

Query Parameters

Parameter Required Type Default Description
name false string null Wildcard search of Reactor Formulas by name
source_token_type false string null Filter Reactor Formulas by source token type

Response

Returns a paginated object with the data property containing an array of Reactor Formulas. Providing any query parameters will filter the results. Returns an error if Reactor Formulas could not be retrieved.

Get a Reactor Formula

Request

curl "https://api.basistheory.com/reactor-formulas/17069df1-80f4-439e-86a7-4121863e4678" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED"
import { BasisTheory } from '@basis-theory/basis-theory-js';

const bt = await new BasisTheory().init('key_N88mVGsp3sCXkykyN2EFED');

const reactorFormula = await bt.reactorFormulas.retrieve('17069df1-80f4-439e-86a7-4121863e4678');
using BasisTheory.net.ReactorFormulas;

var client = new ReactorFormulaClient("key_N88mVGsp3sCXkykyN2EFED");

var reactorFormula = await client.GetByIdAsync("17069df1-80f4-439e-86a7-4121863e4678");
# Coming Soon!

Response

{
  "id": "17069df1-80f4-439e-86a7-4121863e4678",
  "name": "My Private Reactor",
  "description": "Securely exchange token for another token",
  "type": "private",
  "source_token_type": "card",
  "icon": "data:image/png;base64, iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==",
  "code": "
    module.exports = async function (context) {
      // Do something with `context.configuration.SERVICE_API_KEY`

      return {
        data: {
          foo: 'bar',
        },
        metadata: {
          nonSensitiveField: 'Non-Sensitive Value'
        }
      };
    };
  ",
  "configuration": [
    {
      "name": "SERVICE_API_KEY",
      "description": "Configuration description",
      "type": "string"
    }
  ],
  "request_parameters": [
    {
      "name": "REQUEST_PARAMETER_1",
      "description": "Request parameter description",
      "type": "string"
    },
    {
      "name": "REQUEST_PARAMETER_2",
      "description": "Request parameter description",
      "type": "boolean",
      "optional": true
    }
  ],
  "created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
  "created_at": "2020-09-15T15:53:00+00:00",
  "modified_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
  "modified_at": "2021-03-01T08:23:14+00:00"
}

GET https://api.basistheory.com/reactor-formulas/{id}

Get a Reactor Formula by ID in the Tenant.

Permissions

reactor:read

URI Parameters

Parameter Required Type Default Description
id true uuid null The ID of the Reactor Formula

Response

Returns an Reactor Formula with the id provided. Returns an error if the Reactor Formula could not be retrieved.

Update Reactor Formula

Request

curl "https://api.basistheory.com/reator-formula/17069df1-80f4-439e-86a7-4121863e4678" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED" \
  -H "Content-Type: application/json" \
  -X "PUT" \
  -d '{
    "name": "My Private Reactor",
    "description": "Securely exchange token for another token",
    "type": "private",
    "source_token_type": "card",
    "icon": "data:image/png;base64, iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==",
    "code": "
      module.exports = async function (context) {
        // Do something with `context.configuration.SERVICE_API_KEY`

        return {
          foo: 'bar',
        };
      };
    ",
    "configuration": [
      {
        "name": "SERVICE_API_KEY",
        "description": "Configuration description",
        "type": "string"
      }
    ],
    "request_parameters": [
      {
        "name": "REQUEST_PARAMETER_1",
        "description": "Request parameter description",
        "type": "string"
      },
      {
        "name": "REQUEST_PARAMETER_2",
        "description": "Request parameter description",
        "type": "boolean",
        "optional": true
      }
    ]
  }'
import { BasisTheory } from '@basis-theory/basis-theory-js';

const bt = await new BasisTheory().init('key_N88mVGsp3sCXkykyN2EFED');

const reactorFormula = await bt.reactorFormulas.update('17069df1-80f4-439e-86a7-4121863e4678', {
  name: 'My Private Reactor',
  description: 'Securely exchange token for another token',
  type: 'private',
  sourceTokenType: 'card',
  icon: 'data:image/png;base64, iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==',
  code: '
    module.exports = async function (context) {
      // Do something with `context.configuration.SERVICE_API_KEY`

      return {
        foo: 'bar',
      };
    };
  ',
  configuration: [
    {
      name: 'SERVICE_API_KEY',
      description: 'Configuration description',
      type: 'string',
    },
  ],
  requestParameters: [
    {
      name: 'REQUEST_PARAMETER_1',
      description: 'Request parameter description',
      type: 'string',
    },
    {
      name: 'REQUEST_PARAMETER_2',
      description: 'Request parameter description',
      type: 'boolean',
      optional: true
    }
  ],
});
using BasisTheory.net.ReactorFormulas;

var client = new ReactorFormulaClient("key_N88mVGsp3sCXkykyN2EFED");

var reactorFormula = await client.UpdateAsync("17069df1-80f4-439e-86a7-4121863e4678", 
  new ReactorFormula {
    Name = "My Private Reactor",
    Description = "Securely exchange token for another token",
    Type = "private",
    SourceTokenType = "card",
    Icon = "data:image/png;base64, iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==",
    Code = @"
      module.exports = async function (context) {
        // Do something with `context.configuration.SERVICE_API_KEY`

        return {
          foo: 'bar',
        };
      };
    ",
    Configuration = new List<ReactorFormulaConfiguration> {
      new ReactorFormulaConfiguration {
        Name = "SERVICE_API_KEY",
        Description = "Configuration description",
        Type = "string"
      }
    },
    RequestParameters = new List<ReactorFormulaRequestParameter> {
      new ReactorFormulaRequestParameter {
        Name = "REQUEST_PARAMETER_1",
        Description = "Request parameter description",
        Type = "string"
      },
      new ReactorFormulaRequestParameter {
        Name = "REQUEST_PARAMETER_2",
        Description = "Request parameter description",
        Type = "boolean",
        IsOptional = true
      }
    }
  }
);
# Coming Soon!

Response

{
  "id": "17069df1-80f4-439e-86a7-4121863e4678",
  "name": "My Private Reactor",
  "description": "Securely exchange token for another token",
  "type": "private",
  "source_token_type": "card",
  "icon": "data:image/png;base64, iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==",
  "code": "
    module.exports = async function (context) {
      // Do something with `context.configuration.SERVICE_API_KEY`

      return {
        data: {
          foo: 'bar',
        },
        metadata: {
          nonSensitiveField: 'Non-Sensitive Value'
        }
      };
    };
  ",
  "configuration": [
    {
      "name": "SERVICE_API_KEY",
      "description": "Configuration description",
      "type": "string"
    }
  ],
  "request_parameters": [
    {
      "name": "REQUEST_PARAMETER_1",
      "description": "Request parameter description",
      "type": "string"
    },
    {
      "name": "REQUEST_PARAMETER_2",
      "description": "Request parameter description",
      "type": "boolean",
      "optional": true
    }
  ],
  "created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
  "created_at": "2020-09-15T15:53:00+00:00",
  "modified_by": "34053374-d721-43d8-921c-5ee1d337ef21",
  "modified_at": "2021-03-01T08:23:14+00:00"
}

PUT https://api.basistheory.com/reactor-formulas/{id}

Update a Reactor Formula by ID in the Tenant.

Permissions

reactor:update

URI Parameters

Parameter Required Type Default Description
id true uuid null The ID of the Reactor Formula

Request Parameters

Attribute Required Type Default Description
name true string null The name of the Reactor Formula. Has a maximum length of 200
description false string null The description of the Reactor Formula
type true string null Type of the Reactor Formula
source_token_type true string null Source token type of the Reactor Formula
icon false string null Base64 data URL of the image. Supported image types are: image/png, image/jpg, and image/jpeg
code true string null Reactor code which will be executed when the Reactor Formula is processed
configuration true array [] Array of configuration options for configuring a Reactor
request_parameters true array [] Array of request parameters which will be passed when executing the Reactor

Response

Returns an Reactor Formula if the Reactor Formula was updated. Returns an error if there were validation errors, or the Reactor Formula failed to update.

Delete Reactor Formula

Request

curl "https://api.basistheory.com/reactor-formulas/17069df1-80f4-439e-86a7-4121863e4678" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED" \
  -X "DELETE"
import { BasisTheory } from '@basis-theory/basis-theory-js';

const bt = await new BasisTheory().init('key_N88mVGsp3sCXkykyN2EFED');

await bt.reactorFormulas.delete('17069df1-80f4-439e-86a7-4121863e4678');
using BasisTheory.net.ReactorFormulas;

var client = new ReactorFormulaClient("key_N88mVGsp3sCXkykyN2EFED");

await client.DeleteAsync("17069df1-80f4-439e-86a7-4121863e4678");
# Coming Soon!

DELETE https://api.basistheory.com/reactor-formulas/{id}

Delete a Reactor Formula by ID in the Tenant.

Permissions

reactor:delete

URI Parameters

Parameter Required Type Default Description
id true uuid null The ID of the Reactor Formula

Response

Returns an error if the Reactor Formula failed to delete.

Reactors

Reactor Object

Attribute Type Description
id uuid Unique identifier of the Reactor which can be used to get a Reactor
tenant_id uuid The Tenant ID which owns the reactor
name string The name of the reactor
formula Reactor Formula Reactor Formula this Reactor is configured for
configuration map A key-value map of all configuration name and values for an Reactor Formula configuration
created_by uuid (Optional) The ID of the user or Application that created the Reactor
created_at string (Optional) Created date of the Reactor in ISO 8601 format
modified_by uuid (Optional) The ID of the user or Application that last modified the Reactor
modified_at date (Optional) Last modified date of the Reactor in ISO 8601 format

Create Reactor

Request

curl "https://api.basistheory.com/reactors" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED" \
  -H "Content-Type: application/json" \
  -X "POST" \
  -d '{
    "name": "My Reactor",
    "configuration": {
      "SERVICE_API_KEY": "key_abcd1234"
    },
    "formula": {
      "id": "17069df1-80f4-439e-86a7-4121863e4678"
    }
  }'
import { BasisTheory } from '@basis-theory/basis-theory-js';

const bt = await new BasisTheory().init('key_N88mVGsp3sCXkykyN2EFED');

const reactor = await bt.reactors.create({
  name: 'My Reactor',
  configuration: {
    SERVICE_API_KEY: 'key_abcd1234',
  },
  formula: {
    id: '17069df1-80f4-439e-86a7-4121863e4678',
  },
});
using BasisTheory.net.Reactors;

var client = new ReactorClient("key_N88mVGsp3sCXkykyN2EFED");

var reactor = await client.CreateAsync(new Reactor {
  Name = "My Reactor",
  Configuration = new Dictionary<string, string> {
    { "SERVICE_API_KEY", "key_abcd1234" }
  },
  Formula = new Formula {
    Id = new Guid("17069df1-80f4-439e-86a7-4121863e4678")
  }
});
# Coming Soon!

Response

{
  "id": "5b493235-6917-4307-906a-2cd6f1a90b13",
  "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
  "name": "My Reactor",
  "formula": {...},
  "configuration": {
    "SERVICE_API_KEY": "key_abcd1234"
  },
  "created_by": "3ce0dceb-fd0b-4471-8006-c51243c9ef7a",
  "created_at": "2020-09-15T15:53:00+00:00"
}

POST https://api.basistheory.com/reactors

Create a new Reactor from a Reactor Formula for the Tenant.

Permissions

reactor:create

Request Parameters

Attribute Required Type Default Description
name true string null The name of the reactor. Has a maximum length of 200
configuration true object null A key-value map of all configuration name and values for an Reactor Formula configuration
formula.id true uuid null Unique identifier of the Reactor Formula to configure a Reactor for

Response

Returns an reactor if the Reactor was created. Returns an error if there were validation errors, or the Reactor failed to create.

List Reactors

Request

curl "https://api.basistheory.com/reactors" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED"
import { BasisTheory } from '@basis-theory/basis-theory-js';

const bt = await new BasisTheory().init('key_N88mVGsp3sCXkykyN2EFED');

const reactors = await bt.reactors.list();
using BasisTheory.net.Reactors;

var client = new ReactorClient("key_N88mVGsp3sCXkykyN2EFED");

var reactors = await client.GetAsync();
# Coming Soon!

Response

{
  "pagination": {...}
  "data": [
    {
      "id": "5b493235-6917-4307-906a-2cd6f1a90b13",
      "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
      "name": "My Reactor",
      "formula": {...},
      "configuration": {
        "SERVICE_API_KEY": "key_abcd1234"
      },
      "created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
      "created_at": "2020-09-15T15:53:00+00:00",
      "modified_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
      "modified_at": "2021-03-01T08:23:14+00:00"
    },
    {...},
    {...}
  ]
}

GET https://api.basistheory.com/reactors

Get a list of reactors for the Tenant.

Permissions

reactor:read

Query Parameters

Parameter Required Type Default Description
id false array [] An optional list of Reactor ID's to filter the list of reactors by
name false string null Wildcard search of reactors by name
source_token_type false string null Filter reactors by Reactor Formulas source token type

Response

Returns a paginated object with the data property containing an array of reactors. Providing any query parameters will filter the results. Returns an error if reactors could not be retrieved.

Get a Reactor

Request

curl "https://api.basistheory.com/reactors/5b493235-6917-4307-906a-2cd6f1a90b13" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED"
import { BasisTheory } from '@basis-theory/basis-theory-js';

const bt = await new BasisTheory().init('key_N88mVGsp3sCXkykyN2EFED');

const reactor = await bt.reactors.retrieve('5b493235-6917-4307-906a-2cd6f1a90b13');
using BasisTheory.net.Reactors;

var client = new ReactorClient("key_N88mVGsp3sCXkykyN2EFED");

var reactor = await client.GetByIdAsync("5b493235-6917-4307-906a-2cd6f1a90b13");
# Coming Soon!

Response

{
  "id": "5b493235-6917-4307-906a-2cd6f1a90b13",
  "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
  "name": "My Reactor",
  "formula": {...},
  "configuration": {
    "SERVICE_API_KEY": "key_abcd1234"
  },
  "created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
  "created_at": "2020-09-15T15:53:00+00:00",
  "modified_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
  "modified_at": "2021-03-01T08:23:14+00:00"
}

GET https://api.basistheory.com/reactors/{id}

Get a Reactor by ID in the Tenant.

Permissions

reactor:read

URI Parameters

Parameter Required Type Default Description
id true uuid null The ID of the reactor

Response

Returns an reactor with the id provided. Returns an error if the Reactor could not be retrieved.

Update Reactor

Request

curl "https://api.basistheory.com/reactors/5b493235-6917-4307-906a-2cd6f1a90b13" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED" \
  -H "Content-Type: application/json" \
  -X "PUT" \
  -d '{
    "name": "My Reactor",
    "configuration": {
      "SERVICE_API_KEY": "key_abcd1234"
    }
  }'
import { BasisTheory } from '@basis-theory/basis-theory-js';

const bt = await new BasisTheory().init('key_N88mVGsp3sCXkykyN2EFED');

const reactor = await bt.reactors.update('5b493235-6917-4307-906a-2cd6f1a90b13', {
  name: 'My Reactor',
  configuration: {
    SERVICE_API_KEY: 'key_abcd1234',
  },
});
using BasisTheory.net.Reactors;

var client = new ReactorClient("key_N88mVGsp3sCXkykyN2EFED");

var reactor = await client.UpdateAsync("5b493235-6917-4307-906a-2cd6f1a90b13", 
  new Reactor {
    Name = "My Reactor",
    Configuration = new Dictionary<string, string> {
      { "SERVICE_API_KEY", "key_abcd1234" }
    }
  }
);
# Coming Soon!

Response

{
  "id": "5b493235-6917-4307-906a-2cd6f1a90b13",
  "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
  "name": "My Reactor",
  "formula": {...},
  "configuration": {
    "SERVICE_API_KEY": "key_abcd1234"
  },
  "created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
  "created_at": "2020-09-15T15:53:00+00:00",
  "modified_by": "34053374-d721-43d8-921c-5ee1d337ef21",
  "modified_at": "2021-03-01T08:23:14+00:00"
}

PUT https://api.basistheory.com/reactors/{id}

Update a Reactor by ID in the Tenant.

Permissions

reactor:update

URI Parameters

Parameter Required Type Default Description
id true uuid null The ID of the reactor

Request Parameters

Attribute Required Type Default Description
name true string null The name of the reactor. Has a maximum length of 200
configuration true object null A key-value map of all configuration name and values for an Reactor Formula configuration

Response

Returns an reactor if the Reactor was updated. Returns an error if there were validation errors, or the Reactor failed to update.

Delete Reactor

Request

curl "https://api.basistheory.com/reactors/fb124bba-f90d-45f0-9a59-5edca27b3b4a" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED" \
  -X "DELETE"
import { BasisTheory } from '@basis-theory/basis-theory-js';

const bt = await new BasisTheory().init('key_N88mVGsp3sCXkykyN2EFED');

await bt.reactors.delete('fb124bba-f90d-45f0-9a59-5edca27b3b4a');
using BasisTheory.net.Reactors;

var client = new ReactorClient("key_N88mVGsp3sCXkykyN2EFED");

await client.DeleteAsync("fb124bba-f90d-45f0-9a59-5edca27b3b4a");
# Coming Soon!

DELETE https://api.basistheory.com/reactors/{id}

Delete a Reactor by ID in the Tenant.

Permissions

reactor:delete

URI Parameters

Parameter Required Type Default Description
id true uuid null The ID of the reactor

Response

Returns an error if the Reactor failed to delete.

Tenants

Tenants provide a way to logically group your Applications and tokens. Common use cases for Tenants may be to create one per environment such as development, QA, and production or to isolate business domains from each other. Tenant data is isolated from other tenants unless explicitly shared.

Tenant Object

Attribute Type Description
id uuid Unique identifier of the Tenants
owner_id uuid The user ID which owns the Tenants
name string The name of the Tenants
created_by uuid (Optional) The ID of the user that created the Tenant
created_at date (Optional) Created date of the Tenant in ISO 8601 format
modified_by uuid (Optional) The ID of the user or Application that last modified the Tenant
modified_at date (Optional) Last modified date of the Tenant in ISO 8601 format

Tenant Usage Report Object

Attribute Type Description
token_report Token Report Token Usage Report for Tenant

Token Report Object

Attribute Type Description
metrics_by_type map<string, TokenTypeMetrics> Token Metrics by TokenType
included_monthly_active_tokens long Number of included monthly active tokens for the billing plan
monthly_active_tokens long Number of tokens that have been created, read, updated, or decrypted in the current month

Token Type Metrics Object

Attribute Type Description
count long Number of tokens
last_created_at date (Optional) Last created date in ISO 8601 format

Get a Tenant

Request

curl "https://api.basistheory.com/tenants/self" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED"
import { BasisTheory } from '@basis-theory/basis-theory-js';

const bt = await new BasisTheory().init('key_N88mVGsp3sCXkykyN2EFED');

const tenant = await bt.tenants.retrieve();
using BasisTheory.net.Tenants;

var client = new TenantClient("key_N88mVGsp3sCXkykyN2EFED");

var tenant = await client.GetSelfAsync();
# Coming Soon!

Response

{
  "id": "f88da999-b124-4a14-acde-cbc121444f14",
  "owner_id": "97cec6e8-a143-4fb4-9ab0-cf7e49242d21",
  "name": "My Tenant",
  "created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
  "created_at": "2020-09-15T15:53:00+00:00",
  "modified_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
  "modified_at": "2021-03-01T08:23:14+00:00"
}

GET https://api.basistheory.com/tenants/self

Retrieves the Tenant associated with the provided BT-API-KEY.

Permissions

tenant:read

Response

Returns a Tenants for the provided BT-API-KEY. Returns an error if the Tenant could not be retrieved.

Update Tenant

Request

curl "https://api.basistheory.com/tenants/self" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED" \
  -H "Content-Type: application/json" \
  -X "PUT" \
  -d '{
    "name": "My Example Tenant"
  }'
import { BasisTheory } from '@basis-theory/basis-theory-js';

const bt = await new BasisTheory().init('key_N88mVGsp3sCXkykyN2EFED');

const tenant = await bt.tenants.update({
  name: 'My Example Tenant',
});
using BasisTheory.net.Tenants;

var client = new TenantClient("key_N88mVGsp3sCXkykyN2EFED");

var tenant = await client.UpdateAsync(new Tenant {
  Name = "My Example Tenant"
});
# Coming Soon!

Response

{
  "id": "f88da999-b124-4a14-acde-cbc121444f14",
  "owner_id": "97cec6e8-a143-4fb4-9ab0-cf7e49242d21",
  "name": "My Example Tenant",
  "created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
  "created_at": "2020-09-15T15:53:00+00:00",
  "modified_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
  "modified_at": "2021-03-01T08:23:14+00:00"
}

PUT https://api.basistheory.com/tenants/self

Update the Tenant associated with the provided BT-API-KEY.

Permissions

tenant:update

Request Parameters

Attribute Required Type Default Description
name true string null The name of the Tenant. Has a maximum length of 200

Response

Returns a tenant if the Tenant was updated. Returns an error if there were validation errors, or the Tenant failed to update.

Delete Tenant

Request

curl "https://api.basistheory.com/tenants/self" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED" \
  -X "DELETE"
import { BasisTheory } from '@basis-theory/basis-theory-js';

const bt = await new BasisTheory().init('key_N88mVGsp3sCXkykyN2EFED');

await bt.tenants.delete();
using BasisTheory.net.Tenants;

var client = new TenantClient("key_N88mVGsp3sCXkykyN2EFED");

await client.DeleteAsync();
# Coming Soon!

DELETE https://api.basistheory.com/tenants/self

Delete the Tenant associated with the provided BT-API-KEY.

Permissions

tenant:delete

Response

Returns an error if the Tenant failed to delete.

Get Tenant Usage Report

Request

curl "https://api.basistheory.com/tenants/self/reports/usage" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED"
import { BasisTheory } from '@basis-theory/basis-theory-js';

const bt = await new BasisTheory().init('key_N88mVGsp3sCXkykyN2EFED');

const tenantUsageReport = await bt.tenants.retrieveUsageReport();
using BasisTheory.net.Tenants;

var client = new TenantClient("key_N88mVGsp3sCXkykyN2EFED");

var tenantUsageReport = await client.GetTenantUsageReportAsync();
# Coming Soon!

Response

{
  "token_report": {
    "metrics_by_type": {
      "token": {
        "count": 123,
        "last_created_at": "2020-09-15T15:53:00+00:00"
      },
      "card": {
        "count": 456,
        "last_created_at": "2020-09-15T15:53:00+00:00"
      },
      "bank": {
        "count": 789,
        "last_created_at": "2020-09-15T15:53:00+00:00"
      }
    },
    "included_monthly_active_tokens": 50,
    "monthly_active_tokens": 987
  }
}

GET https://api.basistheory.com/tenants/self/reports/usage

Retrieves the Tenant Usage Report associated with the provided BT-API-KEY.

Permissions

report:read

Response

Returns a Tenant Usage Report for the provided BT-API-KEY. Returns an error if the Tenant Usage Report could not be retrieved.

Token Types

Basis Theory offers several pre-configured token types for various use-cases and compliance requirements. Token Types define the rules around a data type such as validation requirements, data classification, data impact level, and data restriction policy.

Token

The token type is used for general data types that don't require input validation or formatting restrictions.

Token Attribute Value
Type token
Default Classification general
Default Impact Level high
Minimum Impact Level low
Default Restriction Policy redact
Input Validation None
Input Length Any
Fingerprinted No

Atomic Card

Token Attribute Value
Type card
Default Classification pci
Default Impact Level high
Minimum Impact Level high
Default Restriction Policy mask
Input Validation See Card Object for validation requirements
Fingerprinted Yes

Atomic Bank

Token Attribute Value
Type bank
Default Classification bank
Default Impact Level high
Minimum Impact Level high
Default Restriction Policy mask
Input Validation See Bank Object for validation requirements
Fingerprinted Yes

Card Number

Token Attribute Value
Type card_number
Default Classification pci
Default Impact Level high
Minimum Impact Level high
Default Restriction Policy mask
Input Validation Luhn-valid, numeric
Input Length 13 - 19
Fingerprinted Yes

Examples:

Input Data Masked Value
4242424242424242 XXXXXXXXXXXX4242
36227206271667 XXXXXXXXXX1667

US Bank Account Number

Token Attribute Value
Type us_bank_account_number
Default Classification bank
Default Impact Level high
Minimum Impact Level high
Default Restriction Policy mask
Input Validation Numeric
Input Length 3 - 17
Fingerprinted Yes

Examples:

Input Data Masked Value
1234567890 XXXXXX7890

US Bank Routing Number

Token Attribute Value
Type us_bank_routing_number
Default Classification bank
Default Impact Level low
Minimum Impact Level low
Default Restriction Policy redact
Input Validation Numeric, ABA-valid
Input Length 9
Fingerprinted Yes

Social Security Number

Token Attribute Value
Type social_security_number
Default Classification pii
Default Impact Level high
Minimum Impact Level high
Default Restriction Policy mask
Input Validation Numeric with optional delimiter of "-"
Input Length 9 (not including delimiting characters)
Fingerprinted Yes

Examples:

Input Data Masked Value
123456789 XXXXX6789
123-45-6789 XXX-XX-6789

Tokens

Token Object

Attribute Type Description
id uuid Unique identifier of the token which can be used to get a token
tenant_id uuid The Tenant ID which owns the token
type string Token type
data any Token data
fingerprint string Uniquely identifies the contents of this token. Fingerprints are only available for Atomic Card and Atomic Bank token types.
privacy privacy object Token Privacy Settings
metadata map A key-value map of non-sensitive data.
encryption encryption object Encryption metadata for an encrypted token data value
created_by uuid (Optional) The Application ID which created the token
created_at date (Optional) Created date of the token in ISO 8601 format
modified_by uuid (Optional) The Application ID which last modified the token
modified_at date (Optional) Last modified date of the token in ISO 8601 format

Encryption Object

Attribute Type Description
cek encryption key Content encryption key
kek encryption key Key encryption key

Encryption Key Object

Attribute Type Description
key string Encryption key or key identifier
prov string Optional encryption provider (e.g. AWS, AZURE, GCP, etc.)
alg string Encryption algorithm (e.g. AES, RSA, etc)

Privacy Object

Token Privacy defines the privacy settings applied to a Token. By default, privacy settings will be applied based on the Token Type. Default privacy settings can be overridden at the time of creation, but only to a setting with a higher specificity level.

Attribute Type Description
classification string Classification of the Token (e.g. general, bank, pci)
impact_level string Impact level of the Token (i.e. low, moderate, high)
restriction_policy string Restriction policy applied to the Token when read by a User or Application with read permissions at a lower impact level (i.e. mask, redact)

Token Classifications

Each token has a data classification associated with it which defines the type of data it contains. Basis Theory permissions access to Tokens based on data classifications (see Token Permissions for more details). The following data classifications are supported:

Name Description Specificity Level
general Contains sensitive data that does not fall under a more specific classification or compliance requirements 0
bank Contains data that falls under banking compliance (e.g. Nacha) 10
pci Contains data that falls under PCI compliance 10
pii Contains user or customer specific identifiers (e.g. email, date of birth, address) 10

Token Impact Levels

Basis Theory follows the standard NIST-defined impact levels of low, moderate, and high to classify the impact unauthorized exposure of a particular piece of data would have on an organization. Token impact levels are used to further classify and permit access to Tokens within a Token Classification.

Name Description Specificity Level
low Loss of data confidentiality, integrity, or availability is expected to have limited adverse effect 0
moderate Loss of data confidentiality, integrity, or availability is expected to have serious adverse effect 1
high Loss of data confidentiality, integrity, or availability is expected to have severe or catastrophic adverse effect 2

Token Restriction Policies

A Token Restriction Policy defines the policy to enforce on a Token's data when read by a User or Application with permission to read the Token's classification but at a lower impact level.

Name Description Specificity Level
mask Token data will be masked in the response, falling back to redact restriction policy if a mask is not available for the Token Type 0
redact Token data will be completely removed in the response 1

Create Token

Request

curl "https://api.basistheory.com/tokens" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED" \
  -H "Content-Type: application/json" \
  -X "POST" \
  -d '{
    "type": "token",
    "data": "Sensitive Value",
    "privacy": {
      "impact_level": "moderate"
    },
    "metadata": {
      "nonSensitiveField": "Non-Sensitive Value"
    }
  }'
import { BasisTheory } from '@basis-theory/basis-theory-js';

const bt = await new BasisTheory().init('key_N88mVGsp3sCXkykyN2EFED');

const token = await bt.tokens.create({
  type: 'token',
  data: 'Sensitive Value',
  privacy: {
    impactLevel: "moderate"
  },
  metadata: {
    nonSensitiveField: 'Non-Sensitive Value'
  }
});
using BasisTheory.net.Tokens;

var client = new TokenClient("key_N88mVGsp3sCXkykyN2EFED");

var token = await client.CreateAsync(new Token {
  Type = "token",
  Data = "Sensitive Value",
  Privacy = new DataPrivacy {
    ImpactLevel = DataImpactLevel.MODERATE
  },
  Metadata = new Dictionary<string, string> {
    { "nonSensitiveField",  "Non-Sensitive Value" }
  }
});
import basistheory
from basistheory.api import tokens_api
from basistheory.model.token import Token

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="key_N88mVGsp3sCXkykyN2EFED")) as api_client:
    token_client = tokens_api.TokensApi(api_client)

    token = token_client.create(token=Token(
        type="token",
        data="Sensitive Value",
        metadata={
            "nonSensitiveField": "Non-Sensitive Value"
        }
    ))

Response

{
  "id": "c06d0789-0a38-40be-b7cc-c28a718f76f1",
  "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
  "type": "token",
  "privacy": {
    "classification": "general",
    "impact_level": "moderate",
    "restriction_policy": "redact"
  },
  "metadata": {
    "nonSensitiveField": "Non-Sensitive Value"
  },
  "created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
  "created_at": "2020-09-15T15:53:00+00:00"
}

POST https://api.basistheory.com/tokens

Create a new token for the Tenant.

Permissions

token:<classification>:create

Request Parameters

Attribute Required Type Default Description
type true string null Token type of the token
data true any null Token data. Can be an object, array, or any primitive type such as an integer, boolean, or string
privacy false privacy object null Token Privacy Settings overrides. Overrides must be a higher specificity level than the default or minimum setting for the Token Type.
metadata false map null A key-value map of non-sensitive data.
encryption false encryption object null Encryption metadata for an encrypted token data value

Response

Returns a token if the token was created. Returns an error if there were validation errors, or the token failed to create.

List Tokens

Request

curl "https://api.basistheory.com/tokens" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED"
import { BasisTheory } from '@basis-theory/basis-theory-js';

const bt = await new BasisTheory().init('key_N88mVGsp3sCXkykyN2EFED');

const tokens = await bt.tokens.list();
using BasisTheory.net.Tokens;

var client = new TokenClient("key_N88mVGsp3sCXkykyN2EFED");

var tokens = await client.GetAsync();
import basistheory
from basistheory.api import tokens_api

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="key_N88mVGsp3sCXkykyN2EFED")) as api_client:
    token_client = tokens_api.TokensApi(api_client)

    tokens = token_client.list()

Response

{
  "pagination": {...},
  "data": [
    {
      "id": "c06d0789-0a38-40be-b7cc-c28a718f76f1",
      "type": "token",
      "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
      "data": null, // Redacted based on Restriction Policy
      "privacy": {
        "classification": "general",
        "impact_level": "moderate",
        "restriction_policy": "redact"
      },
      "metadata": {
        "nonSensitiveField": "Non-Sensitive Value"
      },
      "created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
      "created_at": "2021-03-01T08:23:14+00:00"
    },
    {...},
    {...}
  ]
}

GET https://api.basistheory.com/tokens

Get a list of tokens for the Tenant.

Permissions

token:<classification>:read:<impact_level>

Query Parameters

Parameter Required Type Default Description
id false uuid null One to many Token IDs to retrieve. Multiple IDs can be passed in the form ?id=<value1>&id=<value2>.
type false string null One to many token types to filter the list of tokens by. Can be repeated in the form ?type=<value1>&type=<value2>.
metadata.[key] false map {} Map of key-value pairs to filter tokens with matching metadata in the form ?metadata.key1=value1&metadata.key2=value2. Note, [key] must be unique and repeated keys will be ignored. Metadata will be searched for a case-insensitive, exact match. Multiple parameters will be ANDed together.

Response

Returns a paginated object with the data property containing an array of tokens. Plaintext token data will be returned when the requester has read permissions on the token classification at equal or greater impact level. Token data will be restricted based on the token's restriction policy when the requester has read permissions on the token classification at a lower impact level. Providing any query parameters will filter the results. Returns an error if tokens could not be retrieved.

List Decrypted Tokens DEPRECATED

Request

curl "https://api.basistheory.com/tokens/decrypt" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED"
import { BasisTheory } from '@basis-theory/basis-theory-js';

const bt = await new BasisTheory().init('key_N88mVGsp3sCXkykyN2EFED');

const tokens = await bt.tokens.listDecrypted();
using BasisTheory.net.Tokens;

var client = new TokenClient("key_N88mVGsp3sCXkykyN2EFED");

var tokens = await client.GetAsync(new TokenGetRequest { Decrypt = true });
import basistheory
from basistheory.api import tokens_api

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="key_N88mVGsp3sCXkykyN2EFED")) as api_client:
    token_client = tokens_api.TokensApi(api_client)

    tokens = token_client.list_decrypted()

Response

{
  "pagination": {...},
  "data": [
    {
      "id": "c06d0789-0a38-40be-b7cc-c28a718f76f1",
      "type": "token",
      "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
      "data": "Sensitive Value",
      "privacy": {
        "classification": "general",
        "impact_level": "moderate",
        "restriction_policy": "redact"
      },
      "metadata": {
        "nonSensitiveField": "Non-Sensitive Value"
      },
      "created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
      "created_at": "2021-03-01T08:23:14+00:00"
    },
    {...},
    {...}
  ]
}

GET https://api.basistheory.com/tokens/decrypt

Get a list of decrypted tokens for the Tenant.

Permissions

token:<classification>:read:<impact_level>

Query Parameters

Parameter Required Type Default Description
id false uuid null One to many Token IDs to retrieve. Multiple IDs can be passed in the form ?id=<value1>&id=<value2>.
type false string null One to many token types to filter the list of tokens by. Can be repeated in the form ?type=<value1>&type=<value2>.

Response

Returns a paginated object with the data property containing an array of decrypted tokens. Providing any query parameters will filter the results. Returns an error if tokens could not be retrieved. Token types other than token or non-BasisTheory encrypted tokens will not be decrypted.

Get a Token

Request

curl "https://api.basistheory.com/tokens/c06d0789-0a38-40be-b7cc-c28a718f76f1" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED"
import { BasisTheory } from '@basis-theory/basis-theory-js';

const bt = await new BasisTheory().init('key_N88mVGsp3sCXkykyN2EFED');

const token = await bt.tokens.retrieve('c06d0789-0a38-40be-b7cc-c28a718f76f1');
using BasisTheory.net.Tokens;

var client = new TokenClient("key_N88mVGsp3sCXkykyN2EFED");

var token = await client.GetByIdAsync("c06d0789-0a38-40be-b7cc-c28a718f76f1");
import basistheory
from basistheory.api import tokens_api

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="key_N88mVGsp3sCXkykyN2EFED")) as api_client:
    token_client = tokens_api.TokensApi(api_client)

    token = token_client.get_by_id(id="c06d0789-0a38-40be-b7cc-c28a718f76f1")

Response

{
  "id": "c06d0789-0a38-40be-b7cc-c28a718f76f1",
  "type": "token",
  "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
  "data": null, // Redacted based on Restriction Policy
  "privacy": {
    "classification": "general",
    "impact_level": "moderate",
    "restriction_policy": "redact"
  },
  "metadata": {
    "nonSensitiveField": "Non-Sensitive Value"
  },
  "created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
  "created_at": "2021-03-01T08:23:14+00:00"
}

GET https://api.basistheory.com/tokens/{id}

Get a token by ID in the Tenant.

Permissions

token:<classification>:read:<impact_level>

URI Parameters

Parameter Required Type Default Description
id true uuid null The ID of the token

Response

Returns a token with the id provided. Plaintext token data will be returned when the requester has read permissions on the token classification at equal or greater impact level. Token data will be restricted based on the token's restriction policy when the requester has read permissions on the token classification at a lower impact level. Returns an error if the token could not be retrieved.

Get a Decrypted Token DEPRECATED

Request

curl "https://api.basistheory.com/tokens/c06d0789-0a38-40be-b7cc-c28a718f76f1/decrypt" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED"
import { BasisTheory } from '@basis-theory/basis-theory-js';

const bt = await new BasisTheory().init('key_N88mVGsp3sCXkykyN2EFED');

const token = await bt.tokens.retrieveDecrypted('c06d0789-0a38-40be-b7cc-c28a718f76f1');
using BasisTheory.net.Tokens;

var client = new TokenClient("key_N88mVGsp3sCXkykyN2EFED");

var token = await client.GetByIdAsync("c06d0789-0a38-40be-b7cc-c28a718f76f1", new TokenGetByIdRequest { Decrypt = true });
import basistheory
from basistheory.api import tokens_api

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="key_N88mVGsp3sCXkykyN2EFED")) as api_client:
    token_client = tokens_api.TokensApi(api_client)

    token = token_client.get_decrypted(id="c06d0789-0a38-40be-b7cc-c28a718f76f1")

Response

{
  "id": "c06d0789-0a38-40be-b7cc-c28a718f76f1",
  "type": "token",
  "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
  "data": "Sensitive Value",
  "privacy": {
    "classification": "general",
    "impact_level": "moderate",
    "restriction_policy": "redact"
  },
  "metadata": {
    "nonSensitiveField": "Non-Sensitive Value"
  },
  "created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
  "created_at": "2021-03-01T08:23:14+00:00"
}

GET https://api.basistheory.com/tokens/{id}/decrypt

Get a decrypted token by ID in the Tenant.

Permissions

token:<classification>:read:<impact_level>

URI Parameters

Parameter Required Type Default Description
id true uuid null The ID of the token

Response

Returns a decrypted token with the id provided. Returns an error if the token could not be retrieved. Token types other than token or non-BasisTheory encrypted tokens will not be decrypted.

Delete Token

Request

curl "https://api.basistheory.com/tokens/c06d0789-0a38-40be-b7cc-c28a718f76f1" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED" \
  -X "DELETE"
import { BasisTheory } from '@basis-theory/basis-theory-js';

const bt = await new BasisTheory().init('key_N88mVGsp3sCXkykyN2EFED');

await bt.tokens.delete('c06d0789-0a38-40be-b7cc-c28a718f76f1');
using BasisTheory.net.Tokens;

var client = new TokenClient("key_N88mVGsp3sCXkykyN2EFED");

await client.DeleteAsync("c06d0789-0a38-40be-b7cc-c28a718f76f1");
import basistheory
from basistheory.api import tokens_api

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="key_N88mVGsp3sCXkykyN2EFED")) as api_client:
    token_client = tokens_api.TokensApi(api_client)

    token_client.delete(id="c06d0789-0a38-40be-b7cc-c28a718f76f1")

DELETE https://api.basistheory.com/tokens/{id}

Delete a token by ID in the Tenant.

Permissions

token:<classification>:delete

URI Parameters

Parameter Required Type Default Description
id true uuid null The ID of the token

Response

Returns an error if the token failed to delete.

Token Associations

Token associations allow you to associate any two tokens, of any type, together. This allows you to create parent-child relationships between tokens and traverse between tokens.

Create Token Association

Request

curl "https://api.basistheory.com/tokens/c06d0789-0a38-40be-b7cc-c28a718f76f1/children/c1e565009-1984-4638-8fca-dce8a82cc2af" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED" \
  -H "Content-Type: application/json" \
  -X "POST"
import { BasisTheory } from '@basis-theory/basis-theory-js';

const bt = await new BasisTheory().init('key_N88mVGsp3sCXkykyN2EFED');

await bt.tokens.createAssociation('c06d0789-0a38-40be-b7cc-c28a718f76f1', 
  'c1e565009-1984-4638-8fca-dce8a82cc2af');
using BasisTheory.net.Tokens;

var client = new TokenClient("key_N88mVGsp3sCXkykyN2EFED");

await client.CreateAssociationAsync("c06d0789-0a38-40be-b7cc-c28a718f76f1", 
  "c1e565009-1984-4638-8fca-dce8a82cc2af");
# Coming Soon!

POST https://api.basistheory.com/tokens/{parent_id}/children/{child_id}

Create a new parent/child association between two tokens in the Tenants.

Permissions

Creating an association between two existing tokens requires the appropriate read permission based on the parent and child tokens' privacy settings.

token:<classification>:read:<impact_level>

URI Parameters

Parameter Required Type Default Description
parent_id true uuid null The ID of the parent token
child_id true uuid null The ID of the child token

Response

Returns an error if the token association failed to create.

Delete Token Association

Request

curl "https://api.basistheory.com/tokens/c06d0789-0a38-40be-b7cc-c28a718f76f1/children/c1e565009-1984-4638-8fca-dce8a82cc2af" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED" \
  -H "Content-Type: application/json" \
  -X "DELETE"
import { BasisTheory } from '@basis-theory/basis-theory-js';

const bt = await new BasisTheory().init('key_N88mVGsp3sCXkykyN2EFED');

await bt.tokens.deleteAssociation('c06d0789-0a38-40be-b7cc-c28a718f76f1', 
  'c1e565009-1984-4638-8fca-dce8a82cc2af');
using BasisTheory.net.Tokens;

var client = new TokenClient("key_N88mVGsp3sCXkykyN2EFED");

await client.DeleteAssociationAsync("c06d0789-0a38-40be-b7cc-c28a718f76f1", 
  "c1e565009-1984-4638-8fca-dce8a82cc2af");
# Coming Soon!

DELETE https://api.basistheory.com/tokens/{parent_id}/children/{child_id}

Delete a parent/child association between two tokens in the Tenant.

Permissions

token:<classification>:delete

URI Parameters

Parameter Required Type Default Description
parent_id true uuid null The ID of the parent token
child_id true uuid null The ID of the child token

Response

Returns an error if the token association failed to delete.

Create Child Token for a Token

Request

curl "https://api.basistheory.com/tokens/c06d0789-0a38-40be-b7cc-c28a718f76f1/children" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED" \
  -H "Content-Type: application/json" \
  -X "POST" \
  -d '{
    "type": "token",
    "data": "Sensitive Value",
    "metadata": {
      "nonSensitiveField": "Non-Sensitive Value"
    }
  }'
import { BasisTheory } from '@basis-theory/basis-theory-js';

const bt = await new BasisTheory().init('key_N88mVGsp3sCXkykyN2EFED');

const token = await bt.tokens.createChild('c06d0789-0a38-40be-b7cc-c28a718f76f1', {
  type: 'token',
  data: 'Sensitive Value',
  metadata: {
    nonSensitiveField: 'Non-Sensitive Value'
  }
});
using BasisTheory.net.Tokens;

var client = new TokenClient("key_N88mVGsp3sCXkykyN2EFED");

var token = await client.CreateChildAsync("c06d0789-0a38-40be-b7cc-c28a718f76f1", 
  new Token {
    Type = "token",
    Data = "Sensitive Value",
    Metadata = new Dictionary<string, string> {
      { "nonSensitiveField", "Non-Sensitive Value" }
    }
  }
);
# Coming Soon!

Response

{
  "id": "c1e565009-1984-4638-8fca-dce8a82cc2af",
  "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
  "type": "token",
  "privacy": {
    "classification": "general",
    "impact_level": "high",
    "restriction_policy": "redact"  
  },
  "created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
  "created_at": "2020-09-15T15:53:00+00:00",
  "metadata": {
    "nonSensitiveField": "Non-Sensitive Value"
  }
}

POST https://api.basistheory.com/tokens/{parent_id}/children

Create a new child token a token in the Tenant.

Permissions

Creating a child token requires the appropriate create permission based on the child's classification as well as the appropriate read permission based on the parent token's privacy settings.

token:<classification>:create token:<classification>:read:<impact_level>

URI Parameters

Parameter Required Type Default Description
parent_id true string null The ID of the parent token

Request Parameters

Attribute Required Type Default Description
type true string null Token type of the token
data true any null Token data
privacy false privacy object null Token Privacy Settings
metadata false map null A key-value map of non-sensitive data.
encryption false encryption object null Encryption metadata for an encrypted token data value

Response

Returns a token if the child token was created for the parent token. Returns an error if there were validation errors, or the token failed to create.

List Child Tokens for a Token

Request

curl "https://api.basistheory.com/tokens/c06d0789-0a38-40be-b7cc-c28a718f76f1/children" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED"
import { BasisTheory } from '@basis-theory/basis-theory-js';

const bt = await new BasisTheory().init('key_N88mVGsp3sCXkykyN2EFED');

const tokens = await bt.tokens.listChildren('c06d0789-0a38-40be-b7cc-c28a718f76f1');
using BasisTheory.net.Tokens;

var client = new TokenClient("key_N88mVGsp3sCXkykyN2EFED");

var tokens = await client.GetChildrenAsync("c06d0789-0a38-40be-b7cc-c28a718f76f1");
# Coming Soon!

Response

{
  "pagination": {...},
  "data": [
    {
      "id": "c1e565009-1984-4638-8fca-dce8a82cc2af",
      "type": "token",
      "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
      "data": null, // Redacted based on restriction policy
      "privacy": {
        "classification": "general",
        "impact_level": "high",
        "restriction_policy": "redact"
      },
      "metadata": {
        "nonSensitiveField": "Non-Sensitive Value"
      },
      "created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
      "created_at": "2021-03-01T08:23:14+00:00"
    },
    {...},
    {...}
  ]
}

GET https://api.basistheory.com/tokens/{parent_id}/children

Get a list of child tokens for a token in the Tenant.

Permissions

token:<classification>:read:<impact_level>

URI Parameters

Parameter Required Type Default Description
parent_id true string null The ID of the parent token

Query Parameters

Parameter Required Type Default Description
id false array [] An optional list of token ID's to filter the list of child tokens by
type false array [] An optional array of token types to filter the list of child tokens by

Response

Returns a paginated object with the data property containing an array of child tokens for the parent token. Providing any query parameters will filter the child tokens. Returns an error if tokens could not be retrieved.

Tokenize

The tokenize endpoint enables you to tokenize any request and tokenize several types of tokens in the same request. It can be utilized to combine multiple API calls into a single request to match your current data structure or bulk token creation.

Create Basic Token Request

curl "https://api.basistheory.com/tokenize" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED" \
  -H "Content-Type: application/json" \
  -X "POST" \
  -d '{
    "first_name": "John",
    "last_name": "Doe"
  }'
import { BasisTheory } from '@basis-theory/basis-theory-js';

const bt = await new BasisTheory().init('key_N88mVGsp3sCXkykyN2EFED');

const token = await bt.tokenize({
  first_name: 'John',
  last_name: 'Doe'
});
using BasisTheory.net.Tokenize;

var client = new TokenizeClient("key_N88mVGsp3sCXkykyN2EFED");

var token = await client.Tokenize(new {
  first_name = "John",
  last_name = "Doe"
});
# Coming Soon!

Create Basic Token Response

{
  "first_name": "b0804096-5a47-4b8c-8fb7-b9ecc5e72eec",
  "last_name": "814a6416-3410-4224-8ea9-c0b4d453c9ce"
}

Create Token Request

curl "https://api.basistheory.com/tokenize" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED" \
  -H "Content-Type: application/json" \
  -X "POST" \
  -d '{
    "type": "token",
    "data": "Sensitive Value",
    "metadata": {
      "nonSensitiveField": "Non-Sensitive Value"
    }
  }'
import { BasisTheory } from '@basis-theory/basis-theory-js';

const bt = await new BasisTheory().init('key_N88mVGsp3sCXkykyN2EFED');

const token = await bt.tokenize({
  type: 'token',
  data: 'Sensitive Value',
  metadata: {
    nonSensitiveField: 'Non-Sensitive Value'
  }
});
using BasisTheory.net.Tokenize;

var client = new TokenizeClient("key_N88mVGsp3sCXkykyN2EFED");

var token = await client.Tokenize(new Token {
  Type = "token",
  Data = "Sensitive Value",
  Metadata = new Dictionary<string, string> {
    { "nonSensitiveField",  "Non-Sensitive Value" }
  }
});
# Coming Soon!

Create Token Response

{
  "id": "c06d0789-0a38-40be-b7cc-c28a718f76f1",
  "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
  "type": "token",
  "metadata": {
    "nonSensitiveField": "Non-Sensitive Value"
  },
  "created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
  "created_at": "2020-09-15T15:53:00+00:00"
}

Create Card Request

curl "https://api.basistheory.com/tokenize" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED" \
  -H "Content-Type: application/json" \
  -X "POST" \
  -d '{
    "type": "card",
    "data": {
      "number": "4242424242424242",
      "expiration_month": 12,
      "expiration_year": 2025,
      "cvc": "123"
    },
    "metadata": {
      "nonSensitiveField": "Non-Sensitive Value"
    }
  }'
import { BasisTheory } from '@basis-theory/basis-theory-js';

const bt = await new BasisTheory().init('key_N88mVGsp3sCXkykyN2EFED');

const token = await bt.tokenize({
  type: 'card',
  data: {
    number: '4242424242424242',
    expiration_month: 12,
    expiration_year: 2025,
    cvc: '123'
  },
  metadata: {
    nonSensitiveField: 'Non-Sensitive Value'
  }
});
using BasisTheory.net.Tokenize;

var client = new TokenizeClient("key_N88mVGsp3sCXkykyN2EFED");

var token = await client.Tokenize(new Token {
  Type = "card",
  Data = new Card {
    CardNumber = "4242424242424242",
    ExpirationMonth = 12,
    ExpirationYear = 2025,
    CardVerificationCode = "123"
  },
  Metadata = new Dictionary<string, string> {
    { "nonSensitiveField",  "Non-Sensitive Value" }
  }
});
# Coming Soon!

Create Card Response

{
  "id": "c06d0789-0a38-40be-b7cc-c28a718f76f1",
  "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
  "type": "card",
  "mask": {
    "number": "XXXXXXXXXXXX4242",
    "expiration_month": 12,
    "expiration_year": 2025
  },
  "metadata": {
    "nonSensitiveField": "Non-Sensitive Value"
  },
  "created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
  "created_at": "2020-09-15T15:53:00+00:00"
}

Tokenize Array Request

curl "https://api.basistheory.com/tokenize" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED" \
  -H "Content-Type: application/json" \
  -X "POST" \
  -d '[
    "John",
    "Doe",
    {
      "type": "card",
      "data": {
        "number": "4242424242424242",
        "expiration_month": 12,
        "expiration_year": 2025,
        "cvc": "123"
      }
    },
    {
      "type": "token",
      "data": "Sensitive Value"
    }
  ]'
import { BasisTheory } from '@basis-theory/basis-theory-js';

const bt = await new BasisTheory().init('key_N88mVGsp3sCXkykyN2EFED');

const token = await bt.tokenize([
  'John',
  'Doe',
  {
    type: 'card',
    data: {
      number: '4242424242424242',
      expiration_month: 12,
      expiration_year: 2025,
      cvc: '123'
    },
    metadata: {
      nonSensitiveField: 'Non-Sensitive Value'
    }
  },
  {
    type: 'token',
    data: 'Sensitive Value'
  }
]);
using BasisTheory.net.Tokenize;

var client = new TokenizeClient("key_N88mVGsp3sCXkykyN2EFED");

var token = await client.Tokenize(new object[
  "John",
  "Doe",
  new Token {
    Type = "card",
    Data = new Card {
      CardNumber = "4242424242424242",
      ExpirationMonth = 12,
      ExpirationYear = 2025,
      CardVerificationCode = "123"
    }
  },
  new Token {
    Type = "token",
    Data = "Sensitive Value"
  }
]);
# Coming Soon!

Tokenize Array Response

[
  "b0804096-5a47-4b8c-8fb7-b9ecc5e72eec",
  "814a6416-3410-4224-8ea9-c0b4d453c9ce",
  {
    "id": "c06d0789-0a38-40be-b7cc-c28a718f76f1",
    "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
    "type": "card",
    "mask": {
      "number": "XXXXXXXXXXXX4242",
      "expiration_month": 12,
      "expiration_year": 2025
    },
    "created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
    "created_at": "2020-09-15T15:53:00+00:00"
  },
  {
    "id": "c06d0789-0a38-40be-b7cc-c28a718f76f1",
    "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
    "type": "token",
    "created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
    "created_at": "2020-09-15T15:53:00+00:00"
  }
]

Composite Request

curl "https://api.basistheory.com/tokenize" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED" \
  -H "Content-Type: application/json" \
  -X "POST" \
  -d '{
    "first_name": "John",
    "last_name": "Doe",
    "primary_card": {
      "type": "card",
      "data": {
        "number": "4242424242424242",
        "expiration_month": 12,
        "expiration_year": 2025,
        "cvc": "123"
      }
    },
    "sensitive_tags": [
      "preferred",
      {
        "type": "token",
        "data": "vip"
      }
    ]
  }'
import { BasisTheory } from '@basis-theory/basis-theory-js';

const bt = await new BasisTheory().init('key_N88mVGsp3sCXkykyN2EFED');

const token = await bt.tokenize({
  first_name: 'John',
  last_name: 'Doe',
  primary_card: {
    type: 'card',
    data: {
      number: '4242424242424242',
      expiration_month: 12,
      expiration_year: 2025,
      cvc: '123'
    }
  },
  sensitive_tags: [
    'preferred',
    {
      type: 'token',
      data: 'vip'
    }
  ]
});
using BasisTheory.net.Tokenize;

var client = new TokenizeClient("key_N88mVGsp3sCXkykyN2EFED");

var token = await client.Tokenize(new {
  first_name = "John",
  last_name = "Doe",
  primary_card = new Token {
    Type = "card",
    Data = new Card {
      CardNumber = "4242424242424242",
      ExpirationMonth = 12,
      ExpirationYear = 2025,
      CardVerificationCode = "123"
    }
  },
  sensitive_tags = new object[] {
    "preferred",
    new Token {
      Type = "token",
      Data = "vip"
    }
  }
});
# Coming Soon!

Composite Response

{
  "first_name": "b0804096-5a47-4b8c-8fb7-b9ecc5e72eec",
  "last_name": "814a6416-3410-4224-8ea9-c0b4d453c9ce",
  "primary_card": {
    "id": "c06d0789-0a38-40be-b7cc-c28a718f76f1",
    "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
    "type": "card",
    "mask": {
      "number": "XXXXXXXXXXXX4242",
      "expiration_month": 12,
      "expiration_year": 2025
    },
    "created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
    "created_at": "2020-09-15T15:53:00+00:00"
  },
  "sensitive_tags": [
    "be3dff7a-4e01-4a52-93e6-9f8ef03f3cd9",
    {
      "id": "aaed779a-3152-437d-8e8a-10afeb0fe620",
      "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
      "type": "token",
      "created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
      "created_at": "2020-09-15T15:53:00+00:00"
    }
  ]
}

POST https://api.basistheory.com/tokenize

Tokenize one to many tokens for the Tenant.

Permissions

Permissions are determined by the classification(s) being tokenized and require the appropriate token:<classification>:create permission(s) based on the request.

Deprecations

Deprecated Endpoints

The following table lists deprecated API endpoints and their respective shutdown date.

Endpoint HTTP Method(s) Deprecated Shutdown Date Details
/tokens/decrypt GET January 3, 2022 TBD GET /tokens/decrypt endpoint will be removed in an upcoming release. Token data will now be returned based on the requester's read access. For more information, see List Tokens.
/tokens/{id}/decrypt GET January 3, 2022 TBD GET /tokens/{id}/decrypt endpoint will be removed in an upcoming release. Token data will now be returned based on the requester's read access. For more information, see Get a Token.
/atomic/banks/{id}/decrypt GET January 3, 2022 TBD GET /atomic/banks/{id}/decrypt endpoint will be removed in an upcoming release. Bank data will now be returned based on the requester's read access. For more information, see Get an Atomic Bank.

Deprecated Features

The following table lists deprecated features and their respective shutdown date.

Feature Deprecated Shutdown Date Details
X-API-KEY has been replaced with BT-API-KEY January 9, 2022 March 9, 2022 In order to prevent potential conflicts with the X-API-KEY header while using the Proxy feature, the authentication header for the Basis Theory API has been replaced with BT-API-KEY.
token:*, bank:* and card:* permissions January 3, 2022 January 3, 2022 The following permissions have been removed as of January 3, 2022 (see table for removed permissions and their replacement). New token permissions provide more granular access control based on Data Classification and Impact Level. For more information, see Token Permissions.
Legacy PermissionMigrated To
token:createtoken:general:create
token:readtoken:general:read:low
token:decrypttoken:general:read:high
token:updatetoken:general:update
token:deletetoken:general:delete
token:usetoken:general:use:proxy
bank:createtoken:bank:create
bank:readtoken:bank:read:low
bank:decrypttoken:bank:read:high
bank:updatetoken:bank:update
bank:deletetoken:bank:delete
bank:usetoken:bank:use:proxy
card:createtoken:pci:create
card:readtoken:pci:read:low
card:updatetoken:pci:update
card:deletetoken:pci:delete
card:usetoken:pci:use:proxy