NAV
cURL node.js dotnet
Go to Portal

Get Started

Reference

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

Currently, Basis Theory is in private beta, you can join our waitlist at https://basistheory.com and we will let you know when we are accepting new applicants.

To begin taking advantage of the Basis Theory platform, you’ll need to create an account and tenant through our Portal. This will enable you to manage your token data, create new applications, and authenticate to our API.

If you have an account

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

Install SDK

Install SDK

npm install --save @Basis-Theory/basis-theory-js

dotnet add package BasisTheory.net

Our SDK's 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 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 "X-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'
});

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

// Per call
var client = new TokenClient();
client.GetAsync(requestOptions: new RequestOptions {
  ApiKey = "key_N88mVGsp3sCXkykyN2EFED"
});

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

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

X-API-KEY: key_N88mVGsp3sCXkykyN2EFED

Request correlation

Correlation ID Example:

curl "https://api.basistheory.com" \
  -H "X-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'
});

var client = new TokenClient("key_N88mVGsp3sCXkykyN2EFED");
client.GetAsync(requestOptions: new RequestOptions {
  CorrelationId = "aa5d3379-6385-4ef4-9fdb-ca1341572153"
});

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

All API endpoints accepts 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 "X-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
});

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"
}

Response

Attribute Type Description
errors.{property} array An array of human readable error messages returned per request {property}
status integer HTTP status code of the responses

Error Codes

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

Permissions

Permissions are 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 applications.

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
dependencies array List of downstream permission types which are required for this permission type

Permission Types

Permission Description Application Types Dependencies
tenant:read Read tenants management N/A
tenant:update Update tenants management N/A
tenant:delete Delete tenants management N/A
application:read Read applications management N/A
application:write Create, edit, delete, and regenerate API keys for applications management N/A
reactor:read Read reactor formulas and reactors server_to_server, management token:read
reactor:create Create reactor formulas and reactors management N/A
reactor:update Update reactor formulas and reactors management N/A
reactor:delete Delete reactor formulas and reactors management N/A
log:read Read audit logs management N/A
token:read Read tokens from the vault server_to_server N/A
token:create Create tokens in the vault public, elements, server_to_server N/A
token:delete Delete tokens from the vault server_to_server N/A
card:read Read atomic card tokens server_to_server token:read
card:create Create atomic card tokens public, elements, server_to_server token:create
card:update Update atomic card tokens server_to_server token:create
card:delete Delete atomic card tokens server_to_server token:delete
bank:read Read atomic bank tokens server_to_server token:read
bank:create Create atomic bank tokens public, elements, server_to_server token:create
bank:update Update atomic bank tokens server_to_server token:create
bank:delete Delete atomic bank tokens server_to_server token:delete
bank:decrypt Decrypt atomic bank tokens server_to_server token:read

List Permissions

Request

curl "https://api.basistheory.com/permissions" \
  -H "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"

var client = new PermissionClient("key_N88mVGsp3sCXkykyN2EFED");

var permissions = await client.GetAsync();

Response

[
  {
    "type": "card:read",
    "description": "Read Payment Card tokens",
    "application_types": [
      "server_to_server"
    ],
    "dependencies": [
      "token:read"
    ]
  }, 
  {...},
  {...}
]

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

Response

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

Tenants

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

Tenant Object

Attribute Type Description
id uuid Unique identifier of the tenant
owner_id uuid The user ID which owns the tenant
name string The name of the tenant
created_at date Created date of the application in ISO 8601 format
modified_at date Last modified date of the application in ISO 8601 format

Get a Tenant

Request

curl "https://api.basistheory.com/tenants/self" \
  -H "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"

var client = new TenantClient("key_N88mVGsp3sCXkykyN2EFED");

var tenant = await client.GetSelfAsync();

Response

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

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

Retrieves the tenant associated with the provided X-API-KEY.

Permissions

tenant:read

Response

Returns a tenant for the provided X-API-KEY. Returns an error if the tenant could not be retrieved.

Update Tenant

Request

curl "https://api.basistheory.com/tenants/self" \
  -H "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"
  -H "Content-Type: application/json"
  -X "PUT"
  -D '{
    "name": "My Example Tenant"
  }'

var client = new TenantClient("key_N88mVGsp3sCXkykyN2EFED");

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

Response

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

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

Update the tenant associated with the provided X-API-KEY.

Permissions

application: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 "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"
  -X "DELETE"

var client = new TenantClient("key_N88mVGsp3sCXkykyN2EFED");

await client.DeleteAsync();

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

Delete the tenant associated with the provided X-API-KEY.

Permissions

tenant:write

Response

Returns an error if the tenant failed to delete.

Applications

Your ability to authenticate to the API is granted by creating Applications, each application type has differnet 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_at date Created date of the application in ISO 8601 format
modified_at date 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
Public 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 applications

Create Application

Request

curl "https://api.basistheory.com/applications" \
  -H "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"
  -H "Content-Type: application/json"
  -X "POST"
  -D '{
    "name": "My Example App",
    "type": "server_to_server",
    "permissions": [
      "card:create",
      "card:read",
      "token:create",
      "token:read"
    ]
  }'

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: [
    'card:create',
    'card:read',
    'token:create',
    'token:read',
  ],
});

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> {
    "card:create",
    "card:read",
    "token:create",
    "token:read"
  }
});

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": [
    "card:create",
    "card:read",
    "token:create",
    "token:read"
  ],
  "created_at": "2020-09-15T15:53:00+00:00"
}

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

Create a new application for the tenant.

Permissions

application:write

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 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 "X-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();

var client = new ApplicationClient("key_N88mVGsp3sCXkykyN2EFED");

var applications = await client.GetAsync();

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": [
        "card:create",
        "card:read",
        "token:create",
        "token:read"
      ],
      "created_at": "2020-09-15T15:53:00+00:00",
      "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 "X-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');

var client = new ApplicationClient("key_N88mVGsp3sCXkykyN2EFED");

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

Response

{
  "id": "fe1f9ba4-474e-44b9-b949-110cdba9d662",
  "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
  "name": "My Management App",
  "type": "management",
  "permissions": [
    "application:read",
    "application:write"
  ],
  "created_at": "2020-09-15T15:53:00+00:00",
  "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 "X-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();

var client = new ApplicationClient("key_N88mVGsp3sCXkykyN2EFED");

var application = await client.GetByKeyAsync();

Response

{
  "id": "fe1f9ba4-474e-44b9-b949-110cdba9d662",
  "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
  "name": "My Management App",
  "type": "management",
  "permissions": [
    "application:read",
    "application:write"
  ],
  "created_at": "2020-09-15T15:53:00+00:00",
  "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 X-API-KEY header to lookup the application.

Permissions

application:read

Response

Returns a application for the provided X-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 "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"
  -H "Content-Type: application/json"
  -X "PUT"
  -D '{
    "name": "My Example App",
    "permissions": [
      "application:read",
      "application:write"
    ]
  }'

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: [
    'card:create',
    'card:read',
    'token:create',
    'token:read',
  ],
});

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> {
      "card:create",
      "card:read",
      "token:create",
      "token:read"
    }
  }
);

Response

{
  "id": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
  "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
  "name": "My Example App",
  "type": "management",
  "permissions": [
    "application:read",
    "application:write"
  ],
  "created_at": "2020-09-15T15:53:00+00:00",
  "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:write

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 "X-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');

var client = new ApplicationClient("key_N88mVGsp3sCXkykyN2EFED");

var application = await client.RegenerateKeyAsync(new Guid("fb124bba-f90d-45f0-9a59-5edca27b3b4a"));

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": [
    "card:create",
    "card:read",
    "token:create",
    "token:read"
  ],
  "created_at": "2020-09-15T15:53:00+00:00",
  "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:write

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 "X-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');

var client = new ApplicationClient("key_N88mVGsp3sCXkykyN2EFED");

await client.DeleteAsync(new Guid("fb124bba-f90d-45f0-9a59-5edca27b3b4a"));

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

Delete an application by ID in the tenant.

Permissions

application:write

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.

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 true string
description string null
type string null
source_token_type string null
icon false string
code true string
configuration true array
created_at date Created date of the reactor formula in ISO 8601 format
modified_at date Modified date of the reactor formla in ISO 8601 format

Reactor Formula Configuration Object

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

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

Request

curl "https://api.basistheory.com/reactor-formula" \
  -H "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"
  -H "Content-Type: application/json"
  -X "POST"
  -D '{
    "name": "My Private Reactor",
    "description": "Securely reactor 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",
        "type": "string"
      }
    ]
  }'

var client = new ReactorFormulaClient("key_N88mVGsp3sCXkykyN2EFED");

var reactorFormla = 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<ReactorFormlaConfiguration> {
    new ReactorFormulaConfiguration {
      Name = "SERVICE_API_KEY",
      Type = "string"
    }
  }
});

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",
      "type": "string"
    }
  ],
  "created_at": "2020-09-15T15:53:00+00:00"
}

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

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 formla
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

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 "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"

var client = new ReactorFormulaClient("key_N88mVGsp3sCXkykyN2EFED");

var reactorFormulas = await client.GetAsync();

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",
          "type": "string"
        }
      ],
      "created_at": "2020-09-15T15:53:00+00:00",
      "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-formula/17069df1-80f4-439e-86a7-4121863e4678" \
  -H "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"

var client = new ReactorFormulaClient("key_N88mVGsp3sCXkykyN2EFED");

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

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",
      "type": "string"
    }
  ],
  "created_at": "2020-09-15T15:53:00+00:00",
  "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 reactor 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 "X-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",
        "type": "string"
      }
    ]
  }'

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",
        Type = "string"
      }
    }
  }
);

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",
      "type": "string"
    }
  ],
  "created_at": "2020-09-15T15:53:00+00:00",
  "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 reactor
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

Response

Returns an reactor formula if the reactor reactor 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-formula/17069df1-80f4-439e-86a7-4121863e4678" \
  -H "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"
  -X "DELETE"

var client = new ReactorFormulaClient("key_N88mVGsp3sCXkykyN2EFED");

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

DELETE https://api.basistheory.com/reactor-formula/{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_at string Created date of the reactor in ISO 8601 format
modified_at string Last modified date of the reactor in ISO 8601 format

Create Reactor

Request

curl "https://api.basistheory.com/reactors" \
  -H "X-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"
    }
  }'

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")
  }
});

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_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 "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"

var client = new ReactorClient("key_N88mVGsp3sCXkykyN2EFED");

var reactors = await client.GetAsync();

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_at": "2020-09-15T15:53:00+00:00",
      "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 "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"

var client = new ReactorClient("key_N88mVGsp3sCXkykyN2EFED");

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

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_at": "2020-09-15T15:53:00+00:00",
  "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 "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"
  -H "Content-Type: application/json"
  -X "PUT"
  -D '{
    "name": "My Reactor",
    "configuration": {
      "SERVICE_API_KEY": "key_abcd1234"
    }
  }'

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" }
    }
  }
);

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_at": "2020-09-15T15:53:00+00:00",
  "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 "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"
  -X "DELETE"

var client = new ReactorClient("key_N88mVGsp3sCXkykyN2EFED");

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

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.

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
metadata map A key-value map of non-sensitive data.
encryption encryption object Encryption metadata for an encrypted token data value
children array Array of child tokens where this token is the parent in an association
created_by uuid The application ID which created the token
created_at date Created date of the token in ISO 8601 format

Encryption Object

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

Encryption Key Object

Attribute Required Type Default Description
key string Encryption key or key identifier
alg string Encryption algorithm (e.g. AES, RSA, etc)

Token Types

Name Type Description
Token token Generic token type. This is the default token type if none is provided when creating a new token
Card card Atomic card token type
Bank bank Atomic bank token type
Card Reaction card:reaction This token type is the resulting token type of a reacted Atomic card token
Bank Reaction bank:reaction This token type is the resulting token type of a reacted Atomic bank token

Create Token

Request

curl "https://api.basistheory.com/tokens" \
  -H "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"
  -H "Content-Type: application/json"
  -X "POST"
  -D '{
    "type": "token",
    "data": "ebSG3IohNmg5gTOjN2HBwBbhjDZ6BY3fCWZJfXSucVMfQ+7YNMXQYrPuRSXgSkhuTMYS+BNfVUur4qZSvUbgCA==",
    "metadata": {
      "nonSensitiveField": "Non-Sensitive Value"
    }
    "encryption": {
      "cek": {
        "key": "JLrtGbYSN5/dbqdKtLVG8tHu3QefcZnKsFOPBBXlXcG4zL9US01mW2MqZs6Px4ckSQM8CrRakwLKilrQ0f37Iw==",
        "alg": "AES"
      },
      "kek": {
        "key": "vpXn45HnsoQPR1q8ptngmPvPaqIDJ4vO+FFyQclglePCt8d1SyTDJU0T+F54T7GnAz7vz5OKsjgsFNo9lVB3UA==",
        "alg": "RSA"
      }
    },
    "children": [
      {...},
      {...}
    ]
  }'

var client = new TokenClient("key_N88mVGsp3sCXkykyN2EFED");

var token = await client.CreateAsync(new Token {
  Type = "token",
  Data = "ebSG3IohNmg5gTOjN2HBwBbhjDZ6BY3fCWZJfXSucVMfQ+7YNMXQYrPuRSXgSkhuTMYS+BNfVUur4qZSvUbgCA==",
  Metadata = new Dictionary<string, string> {
    { "nonSensitiveField",  "Non-Sensitive Value" }
  },
  Encryption = new Encryption {
    ContentEncryptionKey = new EncryptionKey {
      Key = "JLrtGbYSN5/dbqdKtLVG8tHu3QefcZnKsFOPBBXlXcG4zL9US01mW2MqZs6Px4ckSQM8CrRakwLKilrQ0f37Iw==",
      Algorithm: "AES"
    },
    KeyEncryptionKey = new EncryptionKey {
      Key = "vpXn45HnsoQPR1q8ptngmPvPaqIDJ4vO+FFyQclglePCt8d1SyTDJU0T+F54T7GnAz7vz5OKsjgsFNo9lVB3UA==",
      Algorithm: "RSA"
    }
  },
  Children = new List<Token> {
    new Token { ... },
    new Token { ... }
  }
});

Response

{
  "id": "c06d0789-0a38-40be-b7cc-c28a718f76f1",
  "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
  "type": "token",
  "metadata": {
    "nonSensitiveField": "Non-Sensitive Value"
  },
  "children": [
    {...},
    {...}
  ],
  "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:create

Request Parameters

Attribute Required Type Default Description
type false string token 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
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
children false array [] An array of tokens. Can be used to bulk create tokens with token associations

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 "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"

var client = new TokenClient("key_N88mVGsp3sCXkykyN2EFED");

var tokens = await client.GetAsync();

Response

{
  "pagination": {...}
  "data": [
    {
      "id": "c06d0789-0a38-40be-b7cc-c28a718f76f1",
      "type": "token",
      "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
      "data": "ebSG3IohNmg5gTOjN2HBwBbhjDZ6BY3fCWZJfXSucVMfQ+7YNMXQYrPuRSXgSkhuTMYS+BNfVUur4qZSvUbgCA==",
      "metadata": {
        "nonSensitiveField": "Non-Sensitive Value"
      }
      "encryption": {
        "cek": {
          "key": "JLrtGbYSN5/dbqdKtLVG8tHu3QefcZnKsFOPBBXlXcG4zL9US01mW2MqZs6Px4ckSQM8CrRakwLKilrQ0f37Iw==",
          "alg": "AES"
        },
        "kek": {
          "key": "vpXn45HnsoQPR1q8ptngmPvPaqIDJ4vO+FFyQclglePCt8d1SyTDJU0T+F54T7GnAz7vz5OKsjgsFNo9lVB3UA==",
          "alg": "RSA"
        }
      },
      "children": [
        {...},
        {...}
      ]
      "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:read

Query Parameters

Parameter Required Type Default Description
id false array [] An optional list of token ID's to filter the list of tokens by
type false array [] An optional array of token types to filter the list of tokens by
children false boolean false Include child tokens where the token is a parent in token association
children_type false array [] An optional array of token types to filter child tokens where the token is a parent in the token association

Response

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

Get a Token

Request

curl "https://api.basistheory.com/tokens/c06d0789-0a38-40be-b7cc-c28a718f76f1" \
  -H "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"

var client = new TokenClient("key_N88mVGsp3sCXkykyN2EFED");

var token = await client.GetByIdAsync("c06d0789-0a38-40be-b7cc-c28a718f76f1");

Response

{
  "id": "c06d0789-0a38-40be-b7cc-c28a718f76f1",
  "type": "token",
  "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
  "data": "ebSG3IohNmg5gTOjN2HBwBbhjDZ6BY3fCWZJfXSucVMfQ+7YNMXQYrPuRSXgSkhuTMYS+BNfVUur4qZSvUbgCA==",
  "metadata": {
    "nonSensitiveField": "Non-Sensitive Value"
  }
  "encryption": {
    "cek": {
      "key": "JLrtGbYSN5/dbqdKtLVG8tHu3QefcZnKsFOPBBXlXcG4zL9US01mW2MqZs6Px4ckSQM8CrRakwLKilrQ0f37Iw==",
      "alg": "AES"
    },
    "kek": {
      "key": "vpXn45HnsoQPR1q8ptngmPvPaqIDJ4vO+FFyQclglePCt8d1SyTDJU0T+F54T7GnAz7vz5OKsjgsFNo9lVB3UA==",
      "alg": "RSA"
    }
  },
  "children": [
    {...},
    {...}
  ]
  "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:read

URI Parameters

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

Query Parameters

Parameter Required Type Default Description
children false boolean false Include child tokens where the token is a parent in token association
children_type false array [] An optional array of token types to filter child tokens where the token is a parent in the token association

Response

Returns a token with the id provided. Returns an error if the token could not be retrieved.

Delete Token

Request

curl "https://api.basistheory.com/tokens/c06d0789-0a38-40be-b7cc-c28a718f76f1" \
  -H "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"
  -X "DELETE"

var client = new TokenClient("key_N88mVGsp3sCXkykyN2EFED");

await client.DeleteAsync("c06d0789-0a38-40be-b7cc-c28a718f76f1");

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

Delete a token by ID in the tenant.

Permissions

token: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 do token traversal between tokens.

Create Token Association

Request

curl "https://api.basistheory.com/tokens/c06d0789-0a38-40be-b7cc-c28a718f76f1/children/c1e565009-1984-4638-8fca-dce8a82cc2af" \
  -H "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"
  -H "Content-Type: application/json"
  -X "POST"

var client = new TokenClient("key_N88mVGsp3sCXkykyN2EFED");

var token = await client.CreateAssociationAsync("c06d0789-0a38-40be-b7cc-c28a718f76f1", 
  "c1e565009-1984-4638-8fca-dce8a82cc2af");

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

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

Permissions

token:create

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 "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"
  -H "Content-Type: application/json"
  -X "DELETE"

var client = new TokenClient("key_N88mVGsp3sCXkykyN2EFED");

var token = await client.DeleteAssociationAsync("c06d0789-0a38-40be-b7cc-c28a718f76f1", 
  "c1e565009-1984-4638-8fca-dce8a82cc2af");

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

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

Permissions

token: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 "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"
  -H "Content-Type: application/json"
  -X "POST"
  -D '{
    "type": "token",
    "data": "ebSG3IohNmg5gTOjN2HBwBbhjDZ6BY3fCWZJfXSucVMfQ+7YNMXQYrPuRSXgSkhuTMYS+BNfVUur4qZSvUbgCA==",
    "metadata": {
      "nonSensitiveField": "Non-Sensitive Value"
    }
    "encryption": {
      "cek": {
        "key": "JLrtGbYSN5/dbqdKtLVG8tHu3QefcZnKsFOPBBXlXcG4zL9US01mW2MqZs6Px4ckSQM8CrRakwLKilrQ0f37Iw==",
        "alg": "AES"
      },
      "kek": {
        "key": "vpXn45HnsoQPR1q8ptngmPvPaqIDJ4vO+FFyQclglePCt8d1SyTDJU0T+F54T7GnAz7vz5OKsjgsFNo9lVB3UA==",
        "alg": "RSA"
      }
    },
    "children": [
      {...},
      {...}
    ]
  }'

var client = new TokenClient("key_N88mVGsp3sCXkykyN2EFED");

var token = await client.CreateChildAsync("c06d0789-0a38-40be-b7cc-c28a718f76f1", 
  new Token {
    Type = "token",
    Data = "ebSG3IohNmg5gTOjN2HBwBbhjDZ6BY3fCWZJfXSucVMfQ+7YNMXQYrPuRSXgSkhuTMYS+BNfVUur4qZSvUbgCA==",
    Metadata = new Dictionary<string, string> {
      { "nonSensitiveField", "Non-Sensitive Value" }
    },
    Encryption = new Encryption {
      ContentEncryptionKey = new EncryptionKey {
        Key = "JLrtGbYSN5/dbqdKtLVG8tHu3QefcZnKsFOPBBXlXcG4zL9US01mW2MqZs6Px4ckSQM8CrRakwLKilrQ0f37Iw==",
        Algorithm: "AES"
      },
      KeyEncryptionKey = new EncryptionKey {
        Key = "vpXn45HnsoQPR1q8ptngmPvPaqIDJ4vO+FFyQclglePCt8d1SyTDJU0T+F54T7GnAz7vz5OKsjgsFNo9lVB3UA==",
        Algorithm: "RSA"
      }
    },
    Children = new List<Token> {
      new Token { ... },
      new Token { ... }
    }
  }
);

Response

{
  "id": "c1e565009-1984-4638-8fca-dce8a82cc2af",
  "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",
  "metadata": {
    "nonSensitiveField": "Non-Sensitive Value"
  },
  "children": [
    {...},
    {...}
  ]
}

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

Create a new child token a token in the tenant.

Permissions

token:create

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 false string token Token type of the token
data true any null Token data
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
children false array [] An array of tokens. Can be used to bulk create tokens with token associations

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 "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"

var client = new TokenClient("key_N88mVGsp3sCXkykyN2EFED");

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

Response

{
  "pagination": {...}
  "data": [
    {
      "id": "c1e565009-1984-4638-8fca-dce8a82cc2af",
      "type": "token",
      "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
      "data": "ebSG3IohNmg5gTOjN2HBwBbhjDZ6BY3fCWZJfXSucVMfQ+7YNMXQYrPuRSXgSkhuTMYS+BNfVUur4qZSvUbgCA==",
      "metadata": {
        "nonSensitiveField": "Non-Sensitive Value"
      }
      "encryption": {
        "cek": {
          "key": "JLrtGbYSN5/dbqdKtLVG8tHu3QefcZnKsFOPBBXlXcG4zL9US01mW2MqZs6Px4ckSQM8CrRakwLKilrQ0f37Iw==",
          "alg": "AES"
        },
        "kek": {
          "key": "vpXn45HnsoQPR1q8ptngmPvPaqIDJ4vO+FFyQclglePCt8d1SyTDJU0T+F54T7GnAz7vz5OKsjgsFNo9lVB3UA==",
          "alg": "RSA"
        }
      },
      "children": [
        {...},
        {...}
      ]
      "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:read

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
children false boolean false Include child tokens where the child token is a parent in token association
children_type false array [] An optional array of token types to filter child tokens where the child token is a parent in the token association

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.

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
billing_details billing details Billing details
metadata map A key-value map of non-sensitive data.
created_by uuid The application ID which created the atomic card
created_at date Created date of the application in ISO 8601 format

Card Object

Attribute Type Description
number string The card number without any separators
expiration_month integer Two-digit number representing the card's expiration month
expiration_year integer Four-digit number representing the card's expiration year

Billing Details Object

Attribute Type Description
name string The cardholder or customer's full name
email string The cardholder or customer's email address
phone string The cardholder or customer's phone number
address address The cardholder or customer's address

Address Object

Attribute Type Description
line1 string Address line 1 (Street address / PO Box / Company name)
line2 string Address line 2 (Apartment / Suite / Unit / Building)
city string City / District / Suburb / Town / Village
state string State / County / Province / Region
postal_code string Zip or postal code
country string Two-character ISO country code (e.g. US)

Create Atomic Card

Request

curl "api.basistheory.com/atomic/cards" \
  -H "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"
  -H "Content-Type: application/json"
  -X "POST"
  -D '{
    "card": {
      "number": "4242424242424242",
      "expiration_month": 12,
      "expiration_year": 2025,
      "cvc": "123"
    },
    "billing_details": {
      "name": "John Doe",
      "email": "[email protected]",
      "phone": "555-123-4567",
      "address": {
        "line1": "111 Test St.",
        "line2": "Apt 304",
        "city": "San Francisco",
        "state": "CA",
        "postal_code": "94141",
        "country": "US"
      }
    },
    "metadata": {
      "nonSensitiveField": "Non-Sensitive Value"
    }
  }'

var client = new AtomicCardClient("key_N88mVGsp3sCXkykyN2EFED");

var atomicCard = await client.CreateAsync(new AtomicCard {
  Card = new Card {
    CardNumber = "4242424242424242",
    ExpirationMonth = 12,
    ExpirationYear = 2025,
    CardVerificationCode = "123"
  },
  BillingDetails = new BillingDetails {
    Name = "John Doe",
    Email = "[email protected]",
    PhoneNumber = "555-123-4567",
    Address = new Address {
      LineOne = "111 Test St.",
      LineTwo = "Apt 304",
      City = "San Francisco",
      State = "CA",
      PostalCode = "94141",
      Country = "US"
    }
  },
  Metadata = new Dictionary<string, string> {
    { "nonSensitiveField", "Non-Sensitive Value" }
  }
});

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
  },
  "billing_details": {
    "name": "John Doe",
    "email": "[email protected]",
    "phone": "555-123-4567",
    "address": {
      "line1": "111 Test St.",
      "line2": "Apt 304",
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94141",
      "country": "US"
    }
  },
  "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/cards

Create a new atomic card for the tenant.

Permissions

card:create token:create

Request Parameters

Attribute Required Type Default Description
card true card null Card data
billing_details false billing details null Billing details
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 "api.basistheory.com/atomic/cards" \
  -H "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"

var client = new AtomicCardClient("key_N88mVGsp3sCXkykyN2EFED");

var atomicCards = await client.GetAsync();

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
      },
      "billing_details": {
        "name": "John Doe",
        "email": "[email protected]",
        "phone": "555-123-4567",
        "address": {
          "line1": "111 Test St.",
          "line2": "Apt 304",
          "city": "San Francisco",
          "state": "CA",
          "postal_code": "94141",
          "country": "US"
        }
      },
      "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

card:read token:read

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 "api.basistheory.com/atomic/cards/c1e565009-1984-4638-8fca-dce8a82cc2af" \
  -H "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"

var client = new AtomicCardClient("key_N88mVGsp3sCXkykyN2EFED");

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

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
  },
  "billing_details": {
    "name": "John Doe",
    "email": "[email protected]",
    "phone": "555-123-4567",
    "address": {
      "line1": "111 Test St.",
      "line2": "Apt 304",
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94141",
      "country": "US"
    }
  },
  "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

card:read token:read

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.

Delete Atomic Card

Request

curl "api.basistheory.com/atomic/cards/c1e565009-1984-4638-8fca-dce8a82cc2af" \
  -H "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"
  -X "DELETE"

var client = new AtomicCardClient("key_N88mVGsp3sCXkykyN2EFED");

await client.DeleteAsync("c1e565009-1984-4638-8fca-dce8a82cc2af");

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

Delete an atomic card by ID in the tenant.

Permissions

card:delete token: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.

Create an Atomic Card Reaction

Request

curl "api.basistheory.com/atomic/cards/c1e565009-1984-4638-8fca-dce8a82cc2af/react" \
  -H "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"
  -X "POST"
  -D '{
    "reactor_id": "5b493235-6917-4307-906a-2cd6f1a90b13",
    "metadata": {
      "nonSensitiveField": "Non-Sensitive Value"
    }
  }'

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

Create an Atomic Card Reaction by ID in the tenant.

Permissions

reactor:read card:create card:read token:create token:read

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
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 token with type of card:reaction if the atomic card was reacted. Returns an error if the atomic card failed to react.

Get an Atomic Card Reaction Token

Request

curl "api.basistheory.com/atomic/cards/c1e565009-1984-4638-8fca-dce8a82cc2af/reaction/6c12a05d-99e3-4454-bdb0-2e6ff88ec5b0" \
  -H "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"
  -X "GET"

GET https://api.basistheory.com/atomic/cards/{atomicCardId}/reaction/{reactionTokenId}

Get an atomic card reaction token by ID in the tenant.

Permissions

card:read token:read

URI Parameters

Parameter Required Type Default Description
atomicCardId true uuid null The ID of the atomic card
reactionTokenId true uuid null The ID of the reaction token

Response

Returns a token with type of card:reaction. Returns an error if the atomic card failed to reacted.

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

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
metadata map A key-value map of non-sensitive data.
created_by uuid The application ID which created the atomic bank
created_at date Created date of the application in ISO 8601 format

Bank Object

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

Create Atomic Bank

Request

curl "https://api.basistheory.com/atomic/banks" \
  -H "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"
  -H "Content-Type: application/json"
  -X "POST"
  -D '{
      "bank": {
        "routing_number": "021000021",
        "account_number": "1234567890"
      },
      "metadata": {
        "nonSensitiveField": "Non-Sensitive Value"
      }
    }
  }'

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" }
  }
});

Response

{
  "id": "1485efb9-6b1f-4248-a5d1-cf9b3907164c",
  "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
  "type": "bank",
  "bank": {
    "routing_number": "021000021",
    "account_number": "XXXXXX7890"
  },
  "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

bank:create token: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 "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"

var client = new AtomicBankClient("key_N88mVGsp3sCXkykyN2EFED");

var atomicBanks = await client.GetAsync();

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"
      },
      "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

bank:read token:read

Response

Returns a paginated object with the data property containing an array of atomic banks. Providing any query parameters will filter the results. 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 "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"

var client = new AtomicBankClient("key_N88mVGsp3sCXkykyN2EFED");

var atomicBank = await client.GetByIdAsync("1485efb9-6b1f-4248-a5d1-cf9b3907164c");

Response

{
  "id": "1485efb9-6b1f-4248-a5d1-cf9b3907164c",
  "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
  "type": "bank",
  "bank": {
    "routing_number": "021000021",
    "account_number": "XXXXXX7890"
  },
  "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

bank:read token:read

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. Returns an error if the atomic bank could not be retrieved.

Delete Atomic Bank

Request

curl "https://api.basistheory.com/atomic/banks/1485efb9-6b1f-4248-a5d1-cf9b3907164c" \
  -H "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"
  -X "DELETE"

var client = new AtomicBankClient("key_N88mVGsp3sCXkykyN2EFED");

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

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

Delete an atomic bank by ID in the tenant.

Permissions

bank:delete token: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

Request

curl "https://api.basistheory.com/atomic/banks/1485efb9-6b1f-4248-a5d1-cf9b3907164c/decrypt" \
  -H "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"

var client = new AtomicBankClient("key_N88mVGsp3sCXkykyN2EFED");

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

Response

{
  "id": "1485efb9-6b1f-4248-a5d1-cf9b3907164c",
  "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
  "type": "bank",
  "bank": {
    "routing_number": "021000021",
    "account_number": "1234567890"
  },
  "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

bank:decrypt token:read

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.

Create an Atomic Bank Reaction

Request

curl "api.basistheory.com/atomic/banks/1485efb9-6b1f-4248-a5d1-cf9b3907164c/react" \
  -H "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"
  -X "POST"
  -D '{
    "reactor_id": "5b493235-6917-4307-906a-2cd6f1a90b13",
    "metadata": {
      "nonSensitiveField": "Non-Sensitive Value"
    }
  }'

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

Create an Atomic Bank Reaction by ID in the tenant.

Permissions

react:read bank:create bank:read token:create token:read

URI Parameters

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

Request Parameters

Parameter Required Type Default Description
ractor_id true uuid null The ID of 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 token with type of bank:reaction if the atomic bank was reacted. Returns an error if the atomic bank failed to react.

Get an Atomic Bank Reaction Token

Request

curl "api.basistheory.com/atomic/banks/1485efb9-6b1f-4248-a5d1-cf9b3907164c/reaction/6c12a05d-99e3-4454-bdb0-2e6ff88ec5b0" \
  -H "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"
  -X "GET"

GET https://api.basistheory.com/atomic/banks/{atomicBankId}/reaction/{reactionTokenId}

Get an atomic bank reaction token by ID in the tenant.

Permissions

bank:read token:read

URI Parameters

Parameter Required Type Default Description
atomicBankId true uuid null The ID of the atomic bank
reactionTokenId true uuid null The ID of the reaction token

Response

Returns a token with type of bank:reaction. Returns an error if the atomic bank failed to react.

Logs

Log Object

Attribute Type Description
tenant_id uuid The tenant ID which owns the entity
application_id uuid The application ID which performed the operation
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 "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"

var client = new LogClient("key_N88mVGsp3sCXkykyN2EFED");

var logs = await client.GetAsync();

Response

{
  "pagination": {...}
  "data": [
    {
      "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
      "application_id": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
      "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.

cURL node.js dotnet