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.

Authentication

Authentication Example:

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

Make sure to replace key_N88mVGsp3sCXkykyN2EFED with your API key.

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"

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

Pagination Request Example:

curl "https://api.basistheory.com/applications?page=2&size=10" \
  -H "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"

Pagination Response Example:

{
  "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.

Response Schema

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

Pagination Response 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 Schema

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
`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 Types

Permission	Description	Application Types	Dependencies
`token:read`	Read tokens from the vault	`server_to_server`	N/A
`token:write`	Write tokens to the vault	`public`, `elements`, `server_to_server`	N/A
`application:read`	Read applications	`management`	N/A
`application:write`	Create, edit, delete, and regenerate API keys for applications	`management`	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:write`
`card:update`	Update atomic card tokens	`server_to_server`	`token:write`
`card:delete`	Delete atomic card tokens	`server_to_server`	`token:write`

List Permissions

List Permissions Request Example:

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

Permissions Response Example:

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

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

Response Schema

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

Response Messages

Code	Description
`200`	Permissions successfully retrieved
`401`	A missing or invalid `X-API-KEY` was provided

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.

Get a Tenant

Get a Tenant Request Example:

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

Tenant Response Example:

{
  "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 Schema

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

Response Messages

Code	Description
`200`	Tenant successfully retrieved
`401`	A missing or invalid `X-API-KEY` was provided
`403`	The provided `X-API-KEY` does not have the required permissions
`404`	The tenant was not found

Update Tenant

Update Tenant Request Example:

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

Update Tenant Response Example:

{
  "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 Schema

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

Response Schema

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

Response Messages

Code	Description
`200`	Tenant successfully updated
`400`	Invalid request body. See Errors response for details
`401`	A missing or invalid `X-API-KEY` was provided
`403`	The provided `X-API-KEY` does not have the required permissions
`404`	The tenant was not found

Delete Tenant

Delete Tenant Request Example:

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

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

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

Permissions

tenant:write

Response Messages

Code	Description
`204`	Tenant successfully deleted
`401`	A missing or invalid `X-API-KEY` was provided
`403`	The provided `X-API-KEY` does not have the required permissions
`404`	The tenant was not found

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

Create Application Request Example:

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:write",
      "token:read"
    ]
  }'

Create Application Response Example:

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

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

Create a new application for the tenant.

Permissions

application:write

Request Schema

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	`[]`	Perimissions for the application

Response Schema

Attribute	Type	Description
`id`	string	Unique identifier of the application which can be used to get an application
`tenant_id`	string	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
`created_at`	string	Created date of the application in ISO 8601 format
`permissions`	array	List of permissions for the application

Response Messages

Code	Description
`201`	Application successfully created
`400`	Invalid request body. See Errors response for details
`401`	A missing or invalid `X-API-KEY` was provided
`403`	The provided `X-API-KEY` does not have the required permissions

List Applications

List Applications Request Example:

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

Applications Response Example:

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

List Applications by IDs Request Example:

curl "https://api.basistheory.com/applications?id=72ef3d62-b7de-4b5f-8aa2-b9db06c291cb&id=3b235ac3-83ea-49c5-8c42-05ba3cbd17d1" \
  -H "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"

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

Get a list of applications for the tenant.

Permissions

application:read

URI Parameters

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

Response Schema

Returns the Pagination schema. The data attribute in the response contains an array of applications with the following schema:

Attribute	Type	Description
`id`	string	Unique identifier of the application which can be used to get an application
`tenant_id`	string	The tenant ID which owns the application
`name`	string	The name of the application
`type`	string	Application type of the application
`created_at`	string	Created date of the application in ISO 8601 format
`modified_at`	string	Last modified date of the application in ISO 8601 format
`permissions`	array	List of permissions for the application

Response Messages

Code	Description
`200`	Applications successfully retrieved
`401`	A missing or invalid `X-API-KEY` was provided
`403`	The provided `X-API-KEY` does not have the required permissions

Get an Application

Get an Application Request Example:

curl "https://api.basistheory.com/applications/fe1f9ba4-474e-44b9-b949-110cdba9d662" \
  -H "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"

Application Response Example:

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

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	string	`null`	The ID of the application

Response Schema

Attribute	Type	Description
`id`	string	Unique identifier of the application which can be used to get an application
`tenant_id`	string	The tenant ID which owns the application
`name`	string	The name of the application
`type`	string	Application type of the application
`created_at`	string	Created date of the application in ISO 8601 format
`modified_at`	string	Last modified date of the application in ISO 8601 format
`permissions`	array	List of permissions for the application

Response Messages

Code	Description
`200`	Application successfully retrieved
`401`	A missing or invalid `X-API-KEY` was provided
`403`	The provided `X-API-KEY` does not have the required permissions
`404`	The application was not found

Get an Application by Key

Get an Application Request Example:

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

Application Response Example:

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

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 Schema

Attribute	Type	Description
`id`	string	Unique identifier of the application which can be used to get an application
`tenant_id`	string	The tenant ID which owns the application
`name`	string	The name of the application
`type`	string	Application type of the application
`created_at`	string	Created date of the application in ISO 8601 format
`modified_at`	string	Last modified date of the application in ISO 8601 format
`permissions`	array	List of permissions for the application

Response Messages

Code	Description
`200`	Application successfully retrieved
`401`	A missing or invalid `X-API-KEY` was provided
`403`	The provided `X-API-KEY` does not have the required permissions
`404`	The application was not found

Update Application

Update Application Request Example:

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

Update Application Response Example:

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

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	string	`null`	The ID of the application

Request Schema

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

Response Schema

Attribute	Type	Description
`id`	string	Unique identifier of the application which can be used to get an application
`tenant_id`	string	The tenant ID which owns the application
`name`	string	The name of the application
`type`	string	Application type of the application
`created_at`	string	Created date of the application in ISO 8601 format
`modified_at`	string	Last modified date of the application in ISO 8601 format
`permissions`	array	List of permissions for the application

Response Messages

Code	Description
`200`	Application successfully updated
`400`	Invalid request body. See Errors response for details
`401`	A missing or invalid `X-API-KEY` was provided
`403`	The provided `X-API-KEY` does not have the required permissions
`404`	The application was not found

Regenerate API Key

Regenerate Application API Key Request Example:

curl "https://api.basistheory.com/applications/fb124bba-f90d-45f0-9a59-5edca27b3b4a/regenerate" \
  -H "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"
  -X "POST"

Regenerate Application API Key Response Example:

{
  "id": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
  "key": "key_FZ8RmaxoGc73lbmF2cpmUJ",
  "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	string	`null`	The ID of the application

Response Schema

Attribute	Type	Description
`id`	string	Unique identifier of the application which can be used to get an application
`key`	string	The API key which should be used for authenticating against Basis Theory API endpoints
`modified_at`	string	Last modified date of the application in ISO 8601 format

Response Messages

Code	Description
`200`	Application API Key successfully regenerated
`400`	Invalid request body. See Errors response for details
`401`	A missing or invalid `X-API-KEY` was provided
`403`	The provided `X-API-KEY` does not have the required permissions
`404`	The application was not found

Delete Application

Delete Application Request Example:

curl "https://api.basistheory.com/applications/fb124bba-f90d-45f0-9a59-5edca27b3b4a" \
  -H "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"
  -X "DELETE"

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	string	`null`	The ID of the application

Response Messages

Code	Description
`204`	Application successfully deleted
`401`	A missing or invalid `X-API-KEY` was provided
`403`	The provided `X-API-KEY` does not have the required permissions
`404`	The application was not found

Tokens

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

Create Token

Create Token Request Example:

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

Create Token Response Example:

{
  "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",
  "metadata": {
    "NonSensitiveField": "Non-Sensitive Value"
  }
}

Create Token Data Examples:

{
  "data": "RandomString"
}

{
  "data": true
}

{
  "data": [1, 2, 3]
}

{
  "data": { 
    "string_field": "RandomString",
    "int_field": 3,
    "bool_field": false,
    "array_field": [1, 2, 3]
    "object_field": {...} 
  }
}

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

Create a new token for the tenant.

Permissions

token:write

Request Schema

Attribute	Required	Type	Default	Description
`type`	false	string	`token`	Token type of the token
`data`	true	any	`null`	Token data
`metadata`	false	any	`null`	Non-sensitive token metadata
`encryption`	false	object	`null`	Encryption metadata for an encrypted token data value

Encryption Object Schema

Attribute	Required	Type	Default	Description
`cek`	false	object	`null`	Content encryption key
`kek`	false	object	`null`	Key encryption key

Encryption Key Object Schema

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

Response Schema

Attribute	Type	Description
`id`	string	Unique identifier of the token which can be used to get a token
`tenant_id`	string	The tenant ID which owns the token
`type`	string	Token type
`created_by`	string	The application ID which created the token
`created_at`	string	Created date of the token in ISO 8601 format
`metadata`	any	The metadata provided when creating the token

Response Messages

Code	Description
`201`	Token successfully created
`400`	Invalid request body. See Errors response for details
`401`	A missing or invalid `X-API-KEY` was provided
`403`	The provided `X-API-KEY` does not have the required permissions

List Tokens

List Tokens Request Example:

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

Tokens Response Example:

{
  "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"
        }
      },
      "created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
      "created_at": "2021-03-01T08:23:14+00:00"
    },
    {...},
    {...}
  ]
}

List Tokens by Type Request Example:

curl "https://api.basistheory.com/tokens?type=card" \
  -H "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"

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

Get a list of tokens for the tenant.

Permissions

token:read

URI Parameters

Parameter	Required	Type	Default	Description
`type`	false	string	`null`	An optional token type to filter the list of tokens by

Response Schema

Returns the Pagination schema. The data attribute in the response contains an array of tokens with the following schema:

Attribute	Type	Description
`id`	string	Unique identifier of the token which can be used to get a token
`tenant_id`	string	The tenant ID which owns the token
`type`	string	Token type
`data`	any	The data provided when creating the token
`metadata`	any	The metadata provided when creating the token
`encryption`	any	The encryption data provided when creating the token
`created_by`	string	The application ID which created the token
`created_at`	string	Created date of the token in ISO 8601 format

Response Messages

Code	Description
`200`	Tokens successfully retrieved
`401`	A missing or invalid `X-API-KEY` was provided
`403`	The provided `X-API-KEY` does not have the required permissions

Get a Token

Get a Token Request Example:

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

Token Response Example:

{
  "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"
    }
  },
  "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	string	`null`	The ID of the token

Response Schema

Attribute	Type	Description
`id`	string	Unique identifier of the token which can be used to get a token
`tenant_id`	string	The tenant ID which owns the token
`type`	string	Token type
`data`	any	The data provided when creating the token
`metadata`	any	The metadata provided when creating the token
`encryption`	any	The encryption data provided when creating the token
`created_by`	string	The application ID which created the token
`created_at`	string	Created date of the token in ISO 8601 format

Response Messages

Code	Description
`200`	Tokens successfully retrieved
`401`	A missing or invalid `X-API-KEY` was provided
`403`	The provided `X-API-KEY` does not have the required permissions
`404`	The token was not found

Delete Token

Delete Token Request Example:

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

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

Delete a token by ID in the tenant.

Permissions

token:write

URI Parameters

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

Response Messages

Code	Description
`204`	Token successfully deleted
`401`	A missing or invalid `X-API-KEY` was provided
`403`	The provided `X-API-KEY` does not have the required permissions
`404`	The token was not found

Atomic Cards

Create Atomic Card

Create Atomic Card Request Example:

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

Create Atomic Card Response Example:

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

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

Create a new atomic card for the tenant.

Permissions

card:create token:write

Request Schema

Attribute	Required	Type	Default	Description
`card`	true	card	`null`	Card object
`billing_details`	false	billing details	`null`	Billing details object

Card Object Schema

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

Billing Details Object Schema

Attribute	Required	Type	Default	Description
`name`	false	string	`null`	The cardholder or customer's full name
`email`	false	string	`null`	The cardholder or customer's email address
`phone`	false	string	`null`	The cardholder or customer's phone number
`address`	false	address	`null`	The cardholder or customer's address

Address Object Schema

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

Response Schema

Attribute	Type	Description
`id`	string	Unique identifier of the token which can be used to get an atomic card
`tenant_id`	string	The tenant ID which owns the card
`type`	string	`Card` token type
`created_by`	string	The application ID which created the atomic card
`created_at`	string	Created date of the application in ISO 8601 format
`card`	card	Masked card object

Response Messages

Code	Description
`201`	Atomic card successfully created
`400`	Invalid request body. See Errors response for details
`401`	A missing or invalid `X-API-KEY` was provided
`403`	The provided `X-API-KEY` does not have the required permissions

List Atomic Cards

List Atomic Cards Request Example:

curl "api.basistheory.com/atomic/cards" \
  -H "X-API-KEY: key_N88mVGsp3sCXkykyN2EFED"

Atomic Cards Response Example:

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

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

Get a list of atomic cards for the tenant.

Permissions

card:read token:read

Response Schema

Returns the Pagination schema. The data attribute in the response contains an array of tokens with the following schema:

Attribute	Type	Description
`id`	string	Unique identifier of the token which can be used to get an atomic card
`tenant_id`	string	The tenant ID which owns the card
`type`	string	`Card` token type
`created_by`	string	The application ID which created the atomic card
`created_at`	string	Created date of the application in ISO 8601 format
`card`	card	Masked card object

Response Messages

Code	Description
`200`	Atomic cards successfully retrieved
`401`	A missing or invalid `X-API-KEY` was provided
`403`	The provided `X-API-KEY` does not have the required permissions

Get an Atomic Card

Get Atomic Card Request Example:

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

Atomic Card Response Example:

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

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	string	`null`	The ID of the atomic card

Response Schema

Attribute	Type	Description
`id`	string	Unique identifier of the token which can be used to get an atomic card
`tenant_id`	string	The tenant ID which owns the card
`type`	string	`Card` token type
`created_by`	string	The application ID which created the atomic card
`created_at`	string	Created date of the application in ISO 8601 format
`card`	card	Masked card object

Response Messages

Code	Description
`200`	Atomic card successfully retrieved
`401`	A missing or invalid `X-API-KEY` was provided
`403`	The provided `X-API-KEY` does not have the required permissions
`404`	The atomic card was not found

Delete Atomic Card

Delete Token Request Example:

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

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

Delete an atomic card by ID in the tenant.

Permissions

card:delete token:write

URI Parameters

Parameter	Required	Type	Default	Description
`id`	true	string	`null`	The ID of the atomic card

Response Messages

Code	Description
`204`	Atomic card successfully deleted
`401`	A missing or invalid `X-API-KEY` was provided
`403`	The provided `X-API-KEY` does not have the required permissions
`404`	The atomic card was not found

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

Create Atomic Bank

Create Atomic Bank Request Example:

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

Create Atomic Bank Response Example:

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

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

Create a new atomic bank for the tenant.

Permissions

bank:create token:write

Request Schema

Attribute	Required	Type	Default	Description
`bank`	true	bank	`null`	Bank object

Bank Object Schema

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

Response Schema

Attribute	Type	Description
`id`	string	Unique identifier of the token which can be used to get an atomic bank
`tenant_id`	string	The tenant ID which owns the bank
`type`	string	`Bank` token type
`created_by`	string	The application ID which created the atomic bank
`created_at`	string	Created date of the application in ISO 8601 format
`bank`	bank	Masked bank object

Response Messages

Code	Description
`201`	Atomic bank successfully created
`400`	Invalid request body. See Errors response for details
`401`	A missing or invalid `X-API-KEY` was provided
`403`	The provided `X-API-KEY` does not have the required permissions

List Atomic Banks

List Atomic Banks Request Example:

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

Atomic Banks Response Example:

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

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

Get a list of atomic banks for the tenant.

Permissions

bank:read token:read

Response Schema

Returns the Pagination schema. The data attribute in the response contains an array of tokens with the following schema:

Attribute	Type	Description
`id`	string	Unique identifier of the token which can be used to get an atomic bank
`tenant_id`	string	The tenant ID which owns the bank
`type`	string	`Bank` token type
`created_by`	string	The application ID which created the atomic bank
`created_at`	string	Created date of the application in ISO 8601 format
`bank`	bank	Masked bank object

Response Messages

Code	Description
`200`	Atomic banks successfully retrieved
`401`	A missing or invalid `X-API-KEY` was provided
`403`	The provided `X-API-KEY` does not have the required permissions

Get an Atomic Bank

Get Atomic Bank Request Example:

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

Atomic Bank Response Example:

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

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	string	`null`	The ID of the atomic bank

Response Schema

Attribute	Type	Description
`id`	string	Unique identifier of the token which can be used to get an atomic bank
`tenant_id`	string	The tenant ID which owns the bank
`type`	string	`Bank` token type
`created_by`	string	The application ID which created the atomic bank
`created_at`	string	Created date of the application in ISO 8601 format
`bank`	bank	Masked bank object

Response Messages

Code	Description
`200`	Atomic bank successfully retrieved
`401`	A missing or invalid `X-API-KEY` was provided
`403`	The provided `X-API-KEY` does not have the required permissions
`404`	The atomic bank was not found

Delete Atomic Bank

Delete Token Request Example:

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

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

Delete an atomic bank by ID in the tenant.

Permissions

bank:delete token:write

URI Parameters

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

Response Messages

Code	Description
`204`	Atomic bank successfully deleted
`401`	A missing or invalid `X-API-KEY` was provided
`403`	The provided `X-API-KEY` does not have the required permissions
`404`	The atomic bank was not found

Decrypt Atomic Bank

Decrypt Token Request Example:

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

Decrypt Atomic Bank Response Example:

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

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	string	`null`	The ID of the atomic bank

Response Schema

Attribute	Type	Description
`id`	string	Unique identifier of the token which can be used to get an atomic bank
`tenant_id`	string	The tenant ID which owns the bank
`type`	string	`Bank` token type
`created_by`	string	The application ID which created the atomic bank
`created_at`	string	Created date of the application in ISO 8601 format
`bank`	bank	Masked bank object

Response Messages

Code	Description
`200`	Atomic bank successfully decrypted
`401`	A missing or invalid `X-API-KEY` was provided
`403`	The provided `X-API-KEY` does not have the required permissions
`404`	The atomic bank was not found

Basis Theory JS

BasisTheory.js module allows consumers to tokenize any data they want within the browser of their customers, or at their backend systems. This will give you the power to continue to own the UX of your application, while still being able to off-load most of the risk and compliance of holding that data.

Install
Initialize
Tokenize
Store Credit Card
Examples

Install

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

# OR

yarn add @Basis-Theory/basis-theory-js

<script src="https://js.basistheory.com"></script>

// checkout shell and html language tabs

// checkout shell and html language tabs

BasisTheory.js is available for including in your site directly from https://js.basistheory.com or installing it as a module, and bundling/hosting it yourself within your site, or using it in your backend systems.

Initialize

// checkout other language tabs

<!-- This adds a window/global BasisTheory variable -->
<script src="https://js.basistheory.com"></script>

<!-- Somewhere in your site code -->
<script>
    // Here is an example on where to init BasisTheory, making sure the page has fully loaded.
    window.addEventListener('load', async () => {
      await BasisTheory.init("test_1234567890");
      // use BasisTheory
    });  
</script>

const BasisTheory = require('@Basis-Theory/basis-theory-js');

BasisTheory.init("test_1234567890").then(() => {
  // use BasisTheory
})

import BasisTheory from '@Basis-Theory/basis-theory-js';

await BasisTheory.init("test_1234567890");
// use BasisTheory

BasisTheory instance should be initialized only once, and it can be done whenever it suits best your workflow.

You will need a public Application API key to initialize the BasisTheory instance, this will give you access to both tokens and atomic features within the module.

The init method returns a short-lived Promise that resolves to the same BasisTheory instance. You may choose to ignore the yielded result, but it is strongly recommended to await for the Promise to resolve before performing any subsequent actions with BasisTheory instance.

Parameter	Required	Type	Description
`apiKey`	true	string	your public application's api key
`options`	false	object	Options

BasisTheory Options

Parameter	Required	Type	Default	Description
`elements`	false	boolean	false	whether to load Hosted Elements

Make sure to replace test_1234567890 with your API key.

Tokenize

BasisTheory.tokens

General tokenization methods can be found under tokens service inside BasisTheory instance.

createToken

# checkout other language tabs

<script src="https://js.basistheory.com"></script>

<script>
  function tokenize() {
    const data = document.getElementById('data-input').value;
    BasisTheory.tokens.createToken(data).then((res) => {
      console.log(res.id)
    })
  }
</script>

<input id="data-input" type="text">
<button onclick="tokenize()">Tokenize</button>

const BasisTheory = require('@Basis-Theory/basis-theory-js');

// sample data
const data = {
  encryptedField: '1vauq19af...',
  myFlag: true,
  values: [1, 2, 3, 4],
}

BasisTheory.tokens.createToken(data)
  .then(function (res) {
    console.log(res.id); //token to store in your system
  });

import BasisTheory from '@Basis-Theory/basis-theory-js';

// sample data
const data = {
  encryptedField: '1vauq19af...',
  myFlag: true,
  values: [1, 2, 3, 4],
}

const { id } = await BasisTheory.tokens.createToken(data)
console.log(id); //token to store in your system

Make sure you've initialized BasisTheory

With createToken method, you can choose to tokenize plain or encrypted data, in any serializable format:

Parameter	Required	Type	Description
`data`	true	string, number, boolean, object or array	The data to tokenize

It returns a Promise that resolves to a TokenCreateResponse object:

Attribute	Type	Description
`id`	string	Unique identifier of the token
`tenantId`	string	The tenant ID which owns the token
`type`	string	Token type
`createdAt`	string	Created date of the token in ISO 8601 format

Internally, BasisTheory.tokens calls Create Token API and maps the response to conventionally named attributes.

getToken

# checkout javascript--node and typescript language tabs

<!-- We don't recommend fetching tokens at client-side -->
<!-- Checkout javascript--node and typescript language tabs. -->

const BasisTheory = require('@Basis-Theory/basis-theory-js');

const id = '25e2cd6b-2373-4cce-b9a0-98a9c65f53fb'; // previously stored token id

BasisTheory.tokens.getToken(id)
  .then(function (token) {
    console.log(token.data);
  });

import BasisTheory from '@Basis-Theory/basis-theory-js';

const id = '25e2cd6b-2373-4cce-b9a0-98a9c65f53fb'; // previously stored token id

const { data } = await BasisTheory.tokens.getToken(id);
console.log(data);

Make sure you've initialized BasisTheory

With getToken method, you can fetch tokenized data by a token id:

Parameter	Required	Type	Description
`id`	true	string	The id of the token

It returns a Promise that resolves to a GetTokenResponse object:

Attribute	Type	Description
`id`	string	Unique identifier of the token
`ownerId`	string	The tenant ID which owns the token
`type`	string	Token type
`data`	any	The data provided when creating the token
`createdAt`	string	Created date of the token in ISO 8601 format

Internally, BasisTheory.tokens calls Get Token API and maps the response to conventionally named attributes.

deleteToken

# checkout javascript--node and typescript language tabs

<!-- We don't recommend deleting tokens at client-side -->
<!-- Checkout javascript--node and typescript language tabs. -->

const BasisTheory = require('@Basis-Theory/basis-theory-js');

const id = '25e2cd6b-2373-4cce-b9a0-98a9c65f53fb'; // previously stored token id

BasisTheory.tokens.delete(id)
  .then(function () {
    // token has been deleted
   });

import BasisTheory from '@Basis-Theory/basis-theory-js';

const id = '25e2cd6b-2373-4cce-b9a0-98a9c65f53fb'; // previously stored token id

await BasisTheory.tokens.deleteToken(id);
// token has been deleted

Make sure you've initialized BasisTheory

With deleteToken method, you can delete tokenized data using a token id:

Parameter	Required	Type	Description
`id`	true	string	The id of the token

It returns a Promise of void.

Internally, BasisTheory.tokens calls Delete Token API.

Atomic

BasisTheory.atomic

storeCreditCard

# checkout other language tabs

<script src="https://js.basistheory.com"></script>

<script>
  function storeCreditCard() {
    const data = {
      card: {
        number: '4242424242424242',
        expirationMonth: 10,
        expirationYear: 25,
        cvc: '000',
      },
      billingDetails: {
        name: 'Fiona Theory',
      },
    };
    BasisTheory.atomic.storeCreditCard(data).then((res) => {
      console.log(res.id)
    })
  }
</script>

const BasisTheory = require('@Basis-Theory/basis-theory-js');

const data = {
  card: {
    number: '4242424242424242',
    expirationMonth: 10,
    expirationYear: 25,
    cvc: '000',
  },
  billingDetails: {
    name: 'Fiona Theory',
  },
};

BasisTheory.atomic.storeCreditCard(data).then((res) => {
  console.log(res.id)
})

import BasisTheory from '@Basis-Theory/basis-theory-js';

const data = {
  card: {
    number: '4242424242424242',
    expirationMonth: 10,
    expirationYear: 25,
    cvc: '000',
  },
  billingDetails: {
    name: 'Fiona Theory',
  },
};

const { id } = await BasisTheory.atomic.storeCreditCard(data);
console.log(res.id);

Make sure you've initialized BasisTheory

With storeCreditCard method, you can tokenize any credit card to securely store and integrate with you atomic cards, in any way you need.

In most scenarios, this reliefs the burden of full PCI compliance.

Attribute	Required	Type	Description
`card`	true	object	CardModel object
`billingDetails`	false	object	BillingDetailsModel object

CardModel

Attribute	Required	Type	Description
`number`	true	string	The card number without any separators
`expirationMonth`	true	integer	Two-digit number representing the card's expiration month
`expirationYear`	true	integer	Four-digit number representing the card's expiration year

BillingDetailsModel

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

AddressModel

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

Examples

We have 2 fully functional examples for how to use our javascript modules to store any data you want into your token infrastructure.

Store PII example

We have a vanilla javascript example that will enable you to create PII in a browser, tokenize it and get a token back to be stored within your system.

Check it out here

Store credit card example

If you have the correct PCI compliant systems and certifications, you'll be able to create atomic cards from within your code using our vanilla javascript example. Follow it here:

Check it out here

Hosted Elements

  BasisTheory.elements

BasisTheory Hosted Elements are simple, secure, developer-friendly inputs that empowers consumers to collect sensitive data from their users directly to Basis Theory certified vault.

Think about it as a portal that we open within your site that allows users to seamlessly tokenize information and never notice they are interacting with our technology. Here is how we make it possible:

We allow you to own your UX, by fully customizing how hosted elements will look like;
Inputs and forms are simple to use, yet we enable you to interact with them similar to how you do with native elements, so you never lose track of your users;

Install / Initialize

// checkout other language tabs

<script src="https://js.basistheory.com"></script>

<!-- Somewhere in your site code -->
<script>
    window.addEventListener('load', async () => {
      await BasisTheory.init("test_1234567890", { elements: true });
      // use BasisTheory.elements
    });  
</script>

const BasisTheory = require('@Basis-Theory/basis-theory-js');

BasisTheory.init("test_1234567890", { elements: true }).then(() => {
  // use BasisTheory.elements
})

import BasisTheory from '@Basis-Theory/basis-theory-js';

await BasisTheory.init("test_1234567890", { elements: true });
// use BasisTheory.elements

Make sure to replace test_1234567890 with your API key.

You don't have to install Hosted Elements as a separated module or include additional script tags besides BasisTheory.js. It will dynamically load them from js.basistheory.com, which enables us to keep the highest compliance standards (e.g. PCI compliance). The only thing you have to worry about is adding elements: true in BasisTheory.init options parameter.

See Basis Theory Initialize for more details.

Elements instance

Create Element

var cardElement = BasisTheory.elements.create('card');

This method returns an instance of an element type.

Parameter	Required	Type	Description
`type`	true	'card'	Type of the element you want to create

Element instance

Mount Element

// checkout html language tab

<div id="my-card"></div>

<script>
  cardElement.mount('#my-card')
</script>

// checkout html language tab

// checkout html language tab

This method attaches the element to the DOM, under a specific container.

Parameter	Required	Type	Description
`selector`	true	string	CSS selector that matches the container where your element will be mounted

Unmount Element

cardElement.unmount();

Safely removes the element from the DOM, stopping any further communication with it.

Element Events

const subscription = element.on('event-type', (event) => {
  // handle event  
});

// subscription.unsubscribe(); // stops listening to the event type

Make sure to replace 'event-type' with an actual event type.

You can communicate with elements by listening to events. When you subscribe to an event, you'll get back a Subscription that you can unsubscribe if/when it fits your workflow.

On Ready

element.on('ready', () => {
  // handle ready event 
})

This event is triggered when the element has rendered and user is able to start interacting with it.

On Change

element.on('change', (changeEvent) => {
  if (changeEvent.complete) {
    // enable submit button  
  } else {
    // disable submit button
    // present validation message
  }
})

This event is triggered whenever element's value(s) relevantly change. For example, if the user types data that doesn't change the state of a field between valid/invalid or empty/filled, you shouldn't expect the event to trigger.

Parameter	Required	Type	Description
`event`	true	'change'	The event type to listen to.
`handler`	true	function	Callback function to be called when the event is fired. Takes in a ChangeEvent.

ChangeEvent

{
  "complete": false,
  "errors": [
    "invalid-field"
  ]
}

Attribute	Type	Description
`complete`	'change'	If the element value is well-formed and is ready to be submitted.
`errors`	array	Array of element validation error types

Store Credit Card

BasisTheory.elements.storeCreditCard({
  card: cardElement,
  billingDetails: {
    name: 'Fiona Theory'  
  }
}).then((token) => {
  console.log(token.id); // token to store
  console.log(JSON.stringify(token.card)); // redacted card data
});

Allows secure submission and tokenization of a card element. Returns a Promise that resoles to the tokenized card data. See CardModel for the resolved value type.

Internally, BasisTheory.elements.storeCreditCard calls Create Atomic Card API.

You can fetch this same data later with Get an Atomic Card API.

storeCreditCard Errors

BasisTheory.elements.storeCreditCard(...).catch(error => {
  // handle error
});

In case storeCreditCard throws an error, that could be related to client-side validation or an unaccepted request from the server.

Attribute	Type	Scope	Description
`validation`	array	client	Array of element validation error types, in case of client-side error.
`response`	object	server	Response body sent from the server.
`status`	number	both	Response HTTP status or `-1` if the request never left the client (i.e. connection issues)

Getting Started

API Reference

Modules

Introduction

What is Basis Theory?

Getting started

Before you begin

If you don't have an account

If you have an account

Authentication

Request correlation

Pagination

Query Parameters

Response Schema

Pagination Response Object

Errors

Response Schema

Error Codes

Permissions

Permission Types

List Permissions

Response Schema

Response Messages

Tenants

Get a Tenant

Permissions

Response Schema

Response Messages

Update Tenant

Permissions

Request Schema

Response Schema

Response Messages

Delete Tenant

Permissions

Response Messages

Applications

Application Types

Create Application

Permissions

Request Schema

Response Schema

Response Messages

List Applications

Permissions

URI Parameters

Response Schema

Response Messages

Get an Application

Permissions

URI Parameters

Response Schema

Response Messages

Get an Application by Key

Permissions

Response Schema

Response Messages

Update Application

Permissions

URI Parameters

Request Schema

Response Schema

Response Messages

Regenerate API Key

Permissions

URI Parameters

Response Schema

Response Messages

Delete Application

Permissions

URI Parameters

Response Messages

Tokens

Token Types

Create Token

Permissions

Request Schema

Encryption Object Schema

Encryption Key Object Schema

Response Schema