Introduction

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

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

What is Basis Theory?

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

Getting started

Before You Begin

If you don't have an account

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

If you have an account

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

Try with Postman

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

Install SDK

Install SDK

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

dotnet add package BasisTheory.net

pip install basistheory

go get github.com/Basis-Theory/basistheory-go/v3

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

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

Authentication

Request

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

import { BasisTheory } from '@basis-theory/basis-theory-js';

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

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

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

using BasisTheory.net.Tokens;

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

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

client.GetAsync(requestOptions: new RequestOptions {
  ApiKey = "key_N88mVGsp3sCXkykyN2EFED"
});

import basistheory
from basistheory.api import tokens_api

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

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

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

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

BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED

Request Correlation

Correlation ID Example:

curl "https://api.basistheory.com" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED" \
  -H "BT-TRACE-ID: aa5d3379-6385-4ef4-9fdb-ca1341572153"

import { BasisTheory } from '@basis-theory/basis-theory-js';

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

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

using BasisTheory.net.Tokens;

var client = new TokenClient("key_N88mVGsp3sCXkykyN2EFED");

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

import basistheory
from basistheory.api import tokens_api

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

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

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

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

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

Pagination

Request

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

import { BasisTheory } from '@basis-theory/basis-theory-js';

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

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

using BasisTheory.net.Applications;

var client = new ApplicationClient("key_N88mVGsp3sCXkykyN2EFED");

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

import basistheory
from basistheory.api import applications_api

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="key_N88mVGsp3sCXkykyN2EFED")) as api_client:
    applications_client = applications_api.ApplicationsApi(api_client)

    applications = applications_client.get(page=2, size=10)

package main

import (
  "context"
  "github.com/Basis-Theory/basistheory-go/v3"
)

func main() {
  configuration := basistheory.NewConfiguration()
  apiClient := basistheory.NewAPIClient(configuration)
  contextWithAPIKey := context.WithValue(context.Background(), basistheory.ContextAPIKeys, map[string]basistheory.APIKey{
    "ApiKey": {Key: "key_N88mVGsp3sCXkykyN2EFED"},
  })

  applications, httpResponse, err := apiClient.ApplicationsApi.Get(contextWithAPIKey).Page(2).Size(10).Execute()
}

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 and List Tokens.

Query Parameters

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

Pagination Object

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

Pagination Metadata Object

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

Errors

{
  "errors": {
    "additionalProp1": [
      "string"
    ],
    "additionalProp2": [
      "string"
    ],
    "additionalProp3": [
      "string"
    ]
  },
  "type": "string",
  "title": "string",
  "status": 400,
  "detail": "string",
  "instance": "string"
}

import { BasisTheory } from '@basis-theory/basis-theory-js';

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

using BasisTheory.net.Common.Errors;
using BasisTheory.net.Tokens;

try {
  var client = new TokenClient("key_N88mVGsp3sCXkykyN2EFED");
  var token = await client.CreateAsync(new Token {...});
} 
catch (BasisTheoryException btex) {
  Console.WriteLine(btex.Message);
  Console.WriteLine(btex.Error.Status); // HTTP status code
  Console.WriteLine(btex.Error.Title);  // error title from HTTP response
  Console.WriteLine(btex.Error.Detail); // error detail from HTTP response

  // (optionally) btex.Error.Errors contains Dictionary of validation errors
}

import basistheory
from basistheory.api import tokens_api
from basistheory.model.create_token_request import CreateTokenRequest

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

    try:
        token = token_client.create(create_token_request=CreateTokenRequest(...))
    except basistheory.ApiException as e:
        print("Exception when calling TokensApi: %s\n" % e)

package main

import (
  "context"
  "github.com/Basis-Theory/basistheory-go/v3"
)

func main() {
  configuration := basistheory.NewConfiguration()
  apiClient := basistheory.NewAPIClient(configuration)
  contextWithAPIKey := context.WithValue(context.Background(), basistheory.ContextAPIKeys, map[string]basistheory.APIKey{
    "ApiKey": {Key: "key_N88mVGsp3sCXkykyN2EFED"},
  })

  createTokenRequest := *basistheory.NewCreateTokenRequest("Sensitive Value")
  ...

  createTokenResponse, createTokenHttpResponse, createErr := apiClient.TokensApi.Create(contextWithAPIKey).CreateTokenRequest(createTokenRequest).Execute()

  if createErr != nil {
    fmt.Printlnf("Create token request failed: %v", createErr)
  }
}

Response

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

Error Codes

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

Reactor Errors

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

Reactor Error Codes

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

IP Addresses

Basis Theory hosts its systems in multiple regions, but utilizes a list of static IP addresses for all outbound network traffic that your systems and firewalls can whitelist for inbound traffic. These IP addresses are static - we will make the best effort to attempt to give 30-day notifications to changes to this list. The following is a list of IP addresses by region for Basis Theory systems:

North America

52.189.39.79
52.189.39.34
20.85.76.209
20.85.77.0
40.122.38.216
52.189.39.70
52.189.39.66
20.85.77.4
20.85.77.29
40.83.13.92

Limits

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

Our Elements are restricted to 10 requests per IP, per second, per Application
Our APIs are restricted to 100 requests per IP, per second, per Application

Error Codes

Error Code	Meaning
`429`	Request has been rate limited

Applications

Your ability to authenticate to the Basis Theory API is granted through an API Key associated with an Application. Each Application type enables different use cases, and you should strive to grant the minimal level of access to each Application. Below, we describe each Application Type and how to choose between them.

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 granted to the Application
`rules`	array	List of access rules granted to the Application
`created_by`	uuid	(Optional) The ID of the user or Application that created the Application
`created_at`	date	(Optional) Created date of the Application in ISO 8601 format
`modified_by`	uuid	(Optional) The ID of the user or Application that last modified the Application
`modified_at`	date	(Optional) Last modified date of the Application in ISO 8601 format
`expires_at`	date	(Optional) Expiring date of the Application in ISO 8601 format
`can_create_expiring_applications`	bool	(Optional) Whether this application can provision Expiring applications

Application Types

Name	Type	Description
Private	`private`	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
Management	`management`	Used for managing all aspects of your token infrastructure such as creating an Application
Expiring	`expiring`	Used for revealing sensitive data using elements within your mobile or browser application

Access Rules

Attribute	Type	Description
`description`	string	A description of this Access Rule
`priority`	int	The priority of the rule, beginning with `1` and higher values having lower precedence
`container`	string	(Optional) The container of Tokens this rule is scoped to
`conditions`	array	(Optional) List of conditions to be satisfied for the rule to be used. Only apply to `Expiring` applications
`transform`	string	The transform to apply to accessed Tokens
`permissions`	array	List of permissions to grant on this Access Rule

See Access Rules for more information.

Access Rule Transforms

Name	Type	Description
Redact	`redact`	Redacts the `data` property from Token responses
Mask	`mask`	Returns the masked value in the `data` property on Token responses if a `mask` is defined, otherwise `data` is redacted
Reveal	`reveal`	Returns the plaintext value in the `data` property in Token responses

Access Rule Conditions

Attribute	Type	Description
`attribute`	string	The token attribute the condition is evaluated on. Either `id` or `container`
`operator`	string	The operator used for the evaluation. Either `starts_with` or `equals`
`value`	string	The value to evaluate against the token attribute

Create Application

Request

curl "https://api.basistheory.com/applications" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED" \
  -H "Content-Type: application/json" \
  -X "POST" \
  -d '{
    "name": "My Example App",
    "type": "private",
    "permissions": [
      "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: 'private',
  permissions: [
    'token:create',
    'token:read',
  ],
});

using BasisTheory.net.Applications;

var client = new ApplicationClient("key_N88mVGsp3sCXkykyN2EFED");

var application = await client.CreateAsync(new Application {
  Name = "My Example App",
  Type = "private",
  Permissions = new List<string> {
    "token:create",
    "token:read"
  }
});

import basistheory
from basistheory.api import applications_api
from basistheory.model.create_application_request import CreateApplicationRequest

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="key_N88mVGsp3sCXkykyN2EFED")) as api_client:
    application_client = applications_api.ApplicationsApi(api_client)

    application = application_client.create(create_application_request=CreateApplicationRequest(
        name="My Example App",
        type="private",
        permissions=[
            "token:create",
            "token:read"
        ]
    ))

package main

import (
  "context"
  "github.com/Basis-Theory/basistheory-go/v3"
)

func main() {
  configuration := basistheory.NewConfiguration()
  apiClient := basistheory.NewAPIClient(configuration)
  contextWithAPIKey := context.WithValue(context.Background(), basistheory.ContextAPIKeys, map[string]basistheory.APIKey{
    "ApiKey": {Key: "key_N88mVGsp3sCXkykyN2EFED"},
  })

  createApplicationRequest := *basistheory.NewCreateApplicationRequest(applicationName, applicationType)
  createApplicationRequest.SetPermissions([]string{
    "token:create",
    "token:read"
  })

  application, httpResponse, err := apiClient.ApplicationsApi.Create(contextWithAPIKey).CreateApplicationRequest(createApplicationRequest).Execute()
}

Response

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

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

Create a new Application for the Tenant.

Permissions

application:create

Request Parameters

Attribute	Required	Type	Default	Description
`name`	true	string	`null`	The name of the Application. Has a maximum length of `200`
`type`	true	string	`null`	Application type of the application
`permissions`	false	array	`[]`	An array of Permissions granted to the application
`rules`	false	array	`[]`	An array of Access Rules granted to the application
`expires_at`	false	string	`Current date + 1 minute`	ISO8601 compatible DateTime in which the application will be deleted. Only applies for `Expiring` applications and must be within a day
`can_create_expiring_applications`	false	bool	`null`	Whether this application can provision Expiring applications. Only applies for `Private` applications

Either permissions or rules is required to be non-empty when creating an Application.

Response

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

List Applications

Request

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

import { BasisTheory } from '@basis-theory/basis-theory-js';

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

const applications = await bt.applications.list();

using BasisTheory.net.Applications;

var client = new ApplicationClient("key_N88mVGsp3sCXkykyN2EFED");

var applications = await client.GetAsync();

import basistheory
from basistheory.api import applications_api

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="key_N88mVGsp3sCXkykyN2EFED")) as api_client:
    application_client = applications_api.ApplicationsApi(api_client)

    applications = application_client.get()

package main

import (
  "context"
  "github.com/Basis-Theory/basistheory-go/v3"
)

func main() {
  configuration := basistheory.NewConfiguration()
  apiClient := basistheory.NewAPIClient(configuration)
  contextWithAPIKey := context.WithValue(context.Background(), basistheory.ContextAPIKeys, map[string]basistheory.APIKey{
    "ApiKey": {Key: "key_N88mVGsp3sCXkykyN2EFED"},
  })

  applications, httpResponse, err := apiClient.ApplicationsApi.Get(contextWithAPIKey).Execute()
}

Response

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

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

Get a list of applications for the Tenant.

Permissions

application:read

Query Parameters

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

Response

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

Get an Application

Request

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

import { BasisTheory } from '@basis-theory/basis-theory-js';

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

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

using BasisTheory.net.Applications;

var client = new ApplicationClient("key_N88mVGsp3sCXkykyN2EFED");

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

import basistheory
from basistheory.api import applications_api

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="key_N88mVGsp3sCXkykyN2EFED")) as api_client:
    application_client = applications_api.ApplicationsApi(api_client)

    application = application_client.get_by_id("fe1f9ba4-474e-44b9-b949-110cdba9d662")

package main

import (
  "context"
  "github.com/Basis-Theory/basistheory-go/v3"
)

func main() {
  configuration := basistheory.NewConfiguration()
  apiClient := basistheory.NewAPIClient(configuration)
  contextWithAPIKey := context.WithValue(context.Background(), basistheory.ContextAPIKeys, map[string]basistheory.APIKey{
    "ApiKey": {Key: "key_N88mVGsp3sCXkykyN2EFED"},
  })

  application, httpResponse, err := apiClient.ApplicationsApi.GetById(contextWithAPIKey, "fe1f9ba4-474e-44b9-b949-110cdba9d662").Execute()
}

Response

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

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

Get an application by ID in the Tenant.

Permissions

application:read

URI Parameters

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

Response

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

Get an Application by Key

Request

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

import { BasisTheory } from '@basis-theory/basis-theory-js';

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

const application = await bt.applications.retrieveByKey();

using BasisTheory.net.Applications;

var client = new ApplicationClient("key_N88mVGsp3sCXkykyN2EFED");

var application = await client.GetByKeyAsync();

import basistheory
from basistheory.api import applications_api

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="key_N88mVGsp3sCXkykyN2EFED")) as api_client:
    application_client = applications_api.ApplicationsApi(api_client)

    application = application_client.get_by_key()

package main

import (
  "context"
  "github.com/Basis-Theory/basistheory-go/v3"
)

func main() {
  configuration := basistheory.NewConfiguration()
  apiClient := basistheory.NewAPIClient(configuration)
  contextWithAPIKey := context.WithValue(context.Background(), basistheory.ContextAPIKeys, map[string]basistheory.APIKey{
    "ApiKey": {Key: "key_N88mVGsp3sCXkykyN2EFED"},
  })

  application, httpResponse, err := apiClient.ApplicationsApi.GetByKey(contextWithCreatedAppAPIKey).Execute()
}

Response

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

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

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

Permissions

application:read

Response

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

Update Application

Request

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

import { BasisTheory } from '@basis-theory/basis-theory-js';

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

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

using BasisTheory.net.Applications;

var client = new ApplicationClient("key_N88mVGsp3sCXkykyN2EFED");

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

import basistheory
from basistheory.api import applications_api
from basistheory.model.update_application_request import UpdateApplicationRequest

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="key_N88mVGsp3sCXkykyN2EFED")) as api_client:
    application_client = applications_api.ApplicationsApi(api_client)

    application = application_client.update("fb124bba-f90d-45f0-9a59-5edca27b3b4a", update_application_request=UpdateApplicationRequest(
        name="My Example App",
        permissions=[
          "application:create",
          "application:read"
        ]
    ))

package main

import (
  "context"
  "github.com/Basis-Theory/basistheory-go/v3"
)

func main() {
  configuration := basistheory.NewConfiguration()
  apiClient := basistheory.NewAPIClient(configuration)
  contextWithAPIKey := context.WithValue(context.Background(), basistheory.ContextAPIKeys, map[string]basistheory.APIKey{
    "ApiKey": {Key: "key_N88mVGsp3sCXkykyN2EFED"},
  })

  updateApplicationRequest := basistheory.NewUpdateApplicationRequest(updatedApplicationName)
  updateApplicationRequest.SetPermissions([]string{
    "application:create",
    "application:read",
  })

  application, httpResponse, err := apiClient.ApplicationsApi.Update(contextWithAPIKey, "fb124bba-f90d-45f0-9a59-5edca27b3b4a").UpdateApplicationRequest(updateApplicationRequest).Execute()
}

Response

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

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

Update an application by ID in the Tenant.

Permissions

application:update

URI Parameters

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

Request Parameters

Attribute	Required	Type	Default	Description
`name`	true	string	`null`	The name of the application. Has a maximum length of `200`
`permissions`	false	array	`[]`	A non-empty array of Permissions granted to the application.
`rules`	false	array	`[]`	An array of Access Rules granted to the application.
`can_create_expiring_applications`	false	bool	`null`	Whether this application can provision `Expiring` applications. Only applies for `Private` applications

Either permissions or rules is required to be non-empty when updating an Application.

Response

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

Regenerate API Key

Request

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

import { BasisTheory } from '@basis-theory/basis-theory-js';

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

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

using BasisTheory.net.Applications;

var client = new ApplicationClient("key_N88mVGsp3sCXkykyN2EFED");

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

import basistheory
from basistheory.api import applications_api

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="key_N88mVGsp3sCXkykyN2EFED")) as api_client:
    application_client = applications_api.ApplicationsApi(api_client)

    application = application_client.regenerate_key("fb124bba-f90d-45f0-9a59-5edca27b3b4a")

package main

import (
  "context"
  "github.com/Basis-Theory/basistheory-go/v3"
)

func main() {
  configuration := basistheory.NewConfiguration()
  apiClient := basistheory.NewAPIClient(configuration)
  contextWithAPIKey := context.WithValue(context.Background(), basistheory.ContextAPIKeys, map[string]basistheory.APIKey{
    "ApiKey": {Key: "key_N88mVGsp3sCXkykyN2EFED"},
  })

  application, httpResponse, err := apiClient.ApplicationsApi.RegenerateKey(contextWithAPIKey, "fb124bba-f90d-45f0-9a59-5edca27b3b4a").Execute()
}

Response

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

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

Regenerate the API key for an application.

Permissions

application:update

URI Parameters

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

Response

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

Delete Application

Request

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

import { BasisTheory } from '@basis-theory/basis-theory-js';

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

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

using BasisTheory.net.Applications;

var client = new ApplicationClient("key_N88mVGsp3sCXkykyN2EFED");

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

import basistheory
from basistheory.api import applications_api

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="key_N88mVGsp3sCXkykyN2EFED")) as api_client:
    application_client = applications_api.ApplicationsApi(api_client)

    application_client.delete("fb124bba-f90d-45f0-9a59-5edca27b3b4a")

package main

import (
  "context"
  "github.com/Basis-Theory/basistheory-go/v3"
)

func main() {
  configuration := basistheory.NewConfiguration()
  apiClient := basistheory.NewAPIClient(configuration)
  contextWithAPIKey := context.WithValue(context.Background(), basistheory.ContextAPIKeys, map[string]basistheory.APIKey{
    "ApiKey": {Key: "key_N88mVGsp3sCXkykyN2EFED"},
  })

  httpResponse, err := apiClient.ApplicationsApi.Delete(contextWithAPIKey, "fb124bba-f90d-45f0-9a59-5edca27b3b4a").Execute()
}

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

Delete an application by ID in the Tenant.

Permissions

application:delete

URI Parameters

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

Response

Returns an error if the application failed to delete.

Logs

Log Object

Attribute	Type	Description
`tenant_id`	uuid	The Tenant ID which owns the entity
`actor_id`	uuid	(Optional) The ID of the actor which performed the operation
`actor_type`	string	(Optional) The type of actor which performed the operation (e.g. `user`, `application`)
`entity_type`	string	The entity type of the log (e.g. `token`, `card`, `bank`, `application`, `tenant`)
`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

Entity Type Object

Attribute	Type	Description
`display_name`	string	A readable string name for the entity type
`value`	string	The system name of the entity. Referenced by a log's `entity_type`

List Logs

Request

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

import { BasisTheory } from '@basis-theory/basis-theory-js';

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

const logs = await bt.logs.list();

using BasisTheory.net.Logs;

var client = new LogClient("key_N88mVGsp3sCXkykyN2EFED");

var logs = await client.GetAsync();

import basistheory
from basistheory.api import logs_api

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="key_N88mVGsp3sCXkykyN2EFED")) as api_client:
    logs_client = logs_api.LogsApi(api_client)

    logs = logs_client.get()

package main

import (
  "context"
  "github.com/Basis-Theory/basistheory-go/v3"
)

func main() {
  configuration := basistheory.NewConfiguration()
  apiClient := basistheory.NewAPIClient(configuration)
  contextWithAPIKey := context.WithValue(context.Background(), basistheory.ContextAPIKeys, map[string]basistheory.APIKey{
    "ApiKey": {Key: "key_N88mVGsp3sCXkykyN2EFED"},
  })

  logs, httpResponse, err := apiClient.LogsApi.Get(contextWithAPIKey).Execute()
}

Response

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

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

Get a list of logs for the Tenant.

Permissions

log:read

Query Parameters

Parameter	Required	Type	Default	Description
`entity_type`	false	string	`null`	An optional entity type to filter the list of logs by. (e.g. `token`, `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.

List Entity Types

Request

curl "https://api.basistheory.com/logs/entity-types" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED"

Response

[
  {
    "display_name": "Application",
    "value": "application"
  },
  {
    "display_name": "Bank",
    "value": "bank"
  },
  {
    "display_name": "Card",
    "value": "card"
  },
  {
    "display_name": "Proxy",
    "value": "proxy"
  },
  ...
]

GET https://api.basistheory.com/logs/entity-types

Get a list of entity types that may be referenced from the logs.

Permissions

log:read

Response

Returns a non-paginated array of entity types.

Permissions

Permissions offer fine-grained control over your Application's access to different resources within your Tenant. We suggest minimizing the scope of your Applications, and to not share Applications across your internal services.

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

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

Permission Object

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

Permission Types

Permission	Description	Application Types
`token:create`	Create Tokens	`public` `private`
`token:update`	Update Tokens	`public` `private`
`token:read`	Read Tokens	`private` `expiring`
`token:search`	Search Tokens	`private`
`token:delete`	Delete Tokens	`private`
`token:use`	Use Tokens in Basis Theory Services (e.g. Proxy, Reactors)	`private`
`tenant:read`	Read Tenants	`management`
`tenant:update`	Update Tenants	`management`
`tenant:delete`	Delete Tenants	`management`
`application:read`	Read Applications	`management`
`application:create`	Create Applications	`management`
`application:update`	Update and regenerate API keys for Applications	`management`
`application:delete`	Delete Applications	`management`
`log:read`	Read audit logs	`management`
`reactor:read`	Read Reactor Formulas and Reactors	`management`
`reactor:create`	Create Reactors Formulas and Reactors	`management`
`reactor:update`	Update Reactors Formulas and Reactors	`management`
`reactor:delete`	Delete Reactors Formulas and Reactors	`management`
`proxy:read`	Read Proxies	`management`
`proxy:create`	Create Proxies	`management`
`proxy:update`	Update Proxies	`management`
`proxy:delete`	Delete Proxies	`management`
`tenant:member:read`	Read Tenant Members	`management`
`tenant:member:update`	Update Tenant Members	`management`
`tenant:member:delete`	Delete Tenant Members	`management`
`tenant:invitation:create`	Create Tenant Invitations	`management`
`tenant:invitation:read`	Read Tenant Invitations	`management`
`tenant:invitation:update`	Update Tenant Invitations	`management`
`tenant:invitation:delete`	Delete Tenant Invitations	`management`
`report:read`	Read reports	`management`

List Permissions

Request

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

import {BasisTheory} from '@basis-theory/basis-theory-js';

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

const permissions = await bt.permissions.list();

using BasisTheory.net.Permissions;

var client = new PermissionClient("key_N88mVGsp3sCXkykyN2EFED");

var permissions = await client.GetAsync();

import basistheory
from basistheory.api import permissions_api

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="key_N88mVGsp3sCXkykyN2EFED")) as api_client:
    permissions_client = permissions_api.PermissionsApi(api_client)

    permissions = permissions_client.get()

package main

import (
  "context"
  "github.com/Basis-Theory/basistheory-go/v3"
)

func main() {
  configuration := basistheory.NewConfiguration()
  apiClient := basistheory.NewAPIClient(configuration)
  contextWithAPIKey := context.WithValue(context.Background(), basistheory.ContextAPIKeys, map[string]basistheory.APIKey{
    "ApiKey": {Key: "key_N88mVGsp3sCXkykyN2EFED"},
  })

  permissions, httpResponse, err := apiClient.PermissionsApi.Get(contextWithAPIKey).Execute()
}

Response

[
  {
    "type": "token:read",
    "description": "Read tokens",
    "application_types": [
      "private"
    ]
  },
  {...},
  {...}
]

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

Gets the list of all supported permissions.

Query Parameters

Parameter	Required	Type	Default	Description
`application_type`	false	string	`null`	Application type to filter permissions by

Response

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

Proxy

Proxying Requests

The Basis Theory Proxy provides a simple way to facilitate the transfer of sensitive data via HTTP API calls. This Proxy can be configured to sit in front of your API to tokenize or transform an inbound request and also between you and a 3rd Party, keeping the sensitive data from touching your systems. To learn more, check out our Proxy Concept.

Basis Theory token identifiers included in the request will be replaced with the raw token data and then the modified request will be forwarded to the destination specified in the BT-PROXY-URL request header. The destination will receive the raw data in the request without your system needing to interact with sensitive data on your own servers.

Some 3rd party services may require whitelisting of Basis Theory IP addresses to allow communication. You can find our IP list here.

Proxy Requests

Request with BT-PROXY-KEY header

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

Request with bt-proxy-key query param

curl "https://api.basistheory.com/proxy?bt-proxy-key=e29a50980ca5" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED" \
  -H "Content-Type: application/json" \
  -X "POST" \
  -d '{
    "parameter1": "{{26818785-547b-4b28-b0fa-531377e99f4e}}",
    "parameter2": "non-sensitive"
  }'

Request with BT-PROXY-URL header

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

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

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

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

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

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

Proxy a request to a third party API.

Authentication

By default, proxy requests must be authenticated using a BT-API-KEY header (see Authentication). Alternatively, pre-configured proxies enable unauthenticated requests from any system, provided the caller knows the unique proxy key. This can be useful for accepting inbound requests that originate from third party systems without the need to share a Basis Theory API key with the third party. See the Configuration section below.

Any authentication required by the destination service can be set on the request and will be forwarded through the proxy (for example, by setting the Authorization header).

Permissions

token:use

The token:use permission is required to use the Proxy, and it is required for each Container of Tokens you wish to detokenize through the Proxy.

Configuration

Basis Theory's Proxy provides two ways to configure a request:

Create a pre-configured Proxy and pass either a BT-PROXY-KEY header or a bt-proxy-key URL query parameter in your request, which will route traffic to the configured destination_url;
Pass the BT-PROXY-URL request header. Its value defines the base URL to which the request will be proxied.

The configured proxy URL must use HTTPS with DNS as the host (explicit IP addresses are not allowed). Destinations must use HTTPS >= TLSv1.2.

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

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

Proxy Transforms

Basis Theory's Proxy supports executing code to transform the proxy request and response. When pre-configuring a Proxy, the request_transform and response_transform properties can optionally be set to an instance of a Proxy Transform. When the request_transform property is set, this Proxy Transform will be executed on the Proxy request and allow you to transform the request body and headers before sending the payload to the destination_url. When the response_transform property is set, this Proxy Transform will be executed on the Proxy response and allow you to transform the response body and headers before sending the response to the originator of the request.

The Transform will receive a JSON object with the following payload:

{
  args: {
    body, // detokenized request body
    headers // request headers
  }
}

Within the transform, the headers and body of the proxy request can be changed. The Transform must respond with the following object, which defines the request body and headers to be sent in the request to the proxy destination_url:

{
  body,
  headers
}

In some situations, you may want to tokenize or detokenize part of the request body. In order to do this, set the application.id property when creating your Proxy. This will inject a pre-configured Basis Theory JS instance into the request:

module.exports = async function (req) {
   const token = await req.bt.tokenize({
      type: 'token',
      data: req.args.body.sensitive_value
  });

  req.args.body.sensitive_value = token.id;

  return {
    body: req.args.body,
    headers: req.args.headers
  }
}

In the above example, we utilized the injected Basis Theory JS instance to tokenize a property called sensitive_value on our request body and passed the token back as the updated sensitive_value to be forwarded to the configured destination_url on our Proxy.

Detokenization

The Basis Theory Proxy will attempt to detokenize any expressions present in the request and inject the raw token data in the request body before it is sent to the downstream destination.

For example, given a token:

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

and a proxy request with the body:

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

then the following request body will be sent to the destination:

{
    "parameter1": "sensitive data",
    "parameter2": "non-sensitive data"
}

The token:use permission is required in order to detokenize tokens within a proxy request. At most, 100 tokens may be detokenized within a single proxy request. You can find more information about the supported detokenization expressions here.

Proxy Responses

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

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

Attribute	Type	Description
`proxy_error`	any	A standard Basis Theory error

Proxies

Proxies provide a way to pre-configure static routes when calling Basis Theory's Proxy. They require you to set a destination URL for where the request will be forwarded to, require authentication to call the proxy, and configure a Reactor which can be executed as part of the request to transform the request body and headers.

Proxies can be utilized for both inbound and outbound calls for things such as webhooks, enabling 3rd parties to call your API or making API calls to 3rd party partners and providers.

Proxy Object

Attribute	Type	Description
`id`	uuid	Unique identifier of the Proxy which can be used to get a Proxy
`key`	string	Auto-generated key used to invoke a particular Proxy
`name`	string	The name of the Proxy
`destination_url`	string	The URL to proxy requests to
`tenant_id`	uuid	The Tenant ID which owns the Proxy
`require_auth`	boolean	Require a `BT-API-KEY` request header for authentication and authorization
`request_transform`	Proxy Transform	(Optional) Transform code which will be executed against the proxy's request before sending to the destination.
`response_transform`	Proxy Transform	(Optional) Transform code which will be executed against the destination's response before returning the proxy response.
`application_id`	string	(Optional) This Application's API key is injected into a pre-configured Node.js BasisTheory instance passed into the Proxy Transform runtime.
`configuration`	map	(Optional) A key-value map of all configuration name and values for a Proxy Transform
`created_by`	uuid	(Optional) The ID of the user or Application that created the Proxy
`created_at`	string	(Optional) Created date of the Proxy in ISO 8601 format
`modified_by`	uuid	(Optional) The ID of the user or Application that last modified the Proxy
`modified_at`	date	(Optional) Last modified date of the Proxy in ISO 8601 format

Proxy Transform Object

Attribute	Type	Description
`code`	string	Transform code which will be executed when the Proxy transform is processed

Transform Code

All transform code snippets must export a function which takes in a request object and returns a response object.

Transform Request Object

Attribute	Type	Description
`args`	object	The arguments containing the `body` and `headers` attributes and an optional `bt` attribute if an `application` was configured on the Proxy object
`configuration`	object	The configuration defined for the Proxy object

Transform Response Object

Attribute	Type	Description
`body`	object	Processed body for the proxy request/response
`headers`	object	Processed headers for the proxy request/response

Transform Code is written in Javascript (targeting Node.js v16) and generally follows the structure:

module.exports = async function (req) {
  const { body, headers, bt } = req.args; // access any args provided with the transform request
  const { MY_CONFIG } = req.configuration; // access any static config defined on the Proxy

  // do anything here!
  const processedBody = ...; // do something with body
  const processedHeaders = ...; // do something with headers

  return {
      body: processedBody, // Proxy request/response body
      headers: processedHeaders // Proxy request/response headers
  };
};

Create a Proxy

Request

curl "https://api.basistheory.com/proxies" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED" \
  -H "Content-Type: application/json" \
  -X "POST" \
  -d '{
    "name": "My Proxy",
    "destination_url": "https://example.com/api",
    "request_transform": {
      "code": "
        module.exports = async function (req) {
          // Do something with `req.configuration.SERVICE_API_KEY`

          return {
            headers: req.args.headers,
            body: req.args.body
          };
        };
      "
    },
    "response_transform": {
      "code": "
        module.exports = async function (req) {
          // Do something with `req.configuration.SERVICE_API_KEY`

          return {
            headers: req.args.headers,
            body: req.args.body
          };
        };
      "
    },
    "configuration": {
      "SERVICE_API_KEY": "key_abcd1234"
    },
    "application": {
      "id": "45c124e7-6ab2-4899-b4d9-1388b0ba9d04"
    },
    "require_auth": true
  }'

import { BasisTheory } from '@basis-theory/basis-theory-js';

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

const proxy = await bt.proxies.create({
  name: 'My Proxy',
  destinationUrl: 'https://example.com/api',
  requestTransform: {
    code: '
      module.exports = async function (req) {
        // Do something with `req.configuration.SERVICE_API_KEY`

        return {
          headers: req.args.headers,
          body: req.args.body
        };
      };
    '
  },
  responseTransform: {
    code: '
      module.exports = async function (req) {
        // Do something with `req.configuration.SERVICE_API_KEY`

        return {
          headers: req.args.headers,
          body: req.args.body
        };
      };
    '
  },
  configuration: {
    SERVICE_API_KEY: 'key_abcd1234',
  },
  application: {
    id: '45c124e7-6ab2-4899-b4d9-1388b0ba9d04'
  },
  requireAuth: true
});

using BasisTheory.net.Proxies;

var client = new ProxyClient("key_N88mVGsp3sCXkykyN2EFED");

var proxy = await client.CreateAsync(new ProxyCreateRequest {
  Name = "My Proxy",
  DestinationUrl = "https://example.com/api",
  RequestTransform = new RequestTransform {
    Code = @"
      module.exports = async function (req) {
        // Do something with `req.configuration.SERVICE_API_KEY`

        return {
          headers: req.args.headers,
          body: req.args.body
        };
      };
    "
  },
  ResponseTransform = new RequestTransform {
    Code = @"
      module.exports = async function (req) {
        // Do something with `req.configuration.SERVICE_API_KEY`

        return {
          headers: req.args.headers,
          body: req.args.body
        };
      };
    "
  },
  Configuration = new Dictionary<string, string> {
    { "SERVICE_API_KEY", "key_abcd1234" }
  },
  Application = new Application {
    Id = new Guid("45c124e7-6ab2-4899-b4d9-1388b0ba9d04")
  },
  RequireAuthentication: true
});

import basistheory
from basistheory.api import proxies_api
from basistheory.model.create_proxy_request import CreateProxyRequest

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="key_N88mVGsp3sCXkykyN2EFED")) as api_client:
    proxy_client = proxies_api.ProxiesApi(api_client)

    proxy = proxy_client.create(create_proxy_request=CreateProxyRequest(
        name="My Proxy",
        destination_url="https://example.com/api",
        requeset_transform=ProxyTransform(
            code=" \
                module.exports = async function (req) { \
                  // Do something with `req.configuration.SERVICE_API_KEY` \

                  "return { \
                    headers: req.args.headers, \
                    body: req.args.body \
                  }; \
                };"
        ),
        response_transform=ProxyTransform(
            code=" \
                module.exports = async function (req) { \
                  // Do something with `req.configuration.SERVICE_API_KEY` \

                  "return { \
                    headers: req.args.headers, \
                    body: req.args.body \
                  }; \
                };"
        ),
        configuration={
            "SERVICE_API_KEY": "key_abcd134"
        },
        application=Application(
            id="45c124e7-6ab2-4899-b4d9-1388b0ba9d04"
        ),
        require_auth=True
    ))

package main

import (
  "context"
  "github.com/Basis-Theory/basistheory-go/v3"
)

func main() {
  configuration := basistheory.NewConfiguration()
  apiClient := basistheory.NewAPIClient(configuration)
  contextWithAPIKey := context.WithValue(context.Background(), basistheory.ContextAPIKeys, map[string]basistheory.APIKey{
    "ApiKey": {Key: "key_N88mVGsp3sCXkykyN2EFED"},
  })

  createProxyRequest := *basistheory.NewCreateProxyRequest("My Proxy", "https://example.com/api")
  requestTransform := *basistheory.NewProxyTransform()
  requestTransform.SetCode(`
    module.exports = async function (req) {
      // Do something with req.configuration.SERVICE_API_KEY

      return {
        headers: req.args.headers,
        body: req.args.body
      };
    };
  `)
  createProxyRequest.SetRequestTransform(requestTransform)
  responseTransform := *basistheory.NewProxyTransform()
  responseTransform.SetCode(`
    module.exports = async function (req) {
      // Do something with req.configuration.SERVICE_API_KEY

      return {
        headers: req.args.headers,
        body: req.args.body
      };
    };
  `)
  createProxyRequest.SetResponseTransform(responseTransform)
  createProxyRequest.SetConfiguration(map[string]string{
    "SERVICE_API_KEY": "key_abcd134",
  })
  application := *basistheory.NewApplication()
  application.SetId("45c124e7-6ab2-4899-b4d9-1388b0ba9d04")
  createProxyRequest.SetApplication(application)
  createProxyRequest.SetRequireAuth(true)

  proxy, httpResponse, err := apiClient.ProxiesApi.Create(contextWithAPIKey).CreateProxyRequest(createProxyRequest).Execute()
}

Response

{
  "id": "433013a6-a614-4e1e-b2aa-5fba67aa85e6",
  "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
  "name": "My Proxy",
  "key": "e29a50980ca5",
  "destination_url": "https://example.com/api",
  "request_transform": {
    "code": "
      module.exports = async function (req) {
        // Do something with req.configuration.SERVICE_API_KEY

        return {
          headers: req.args.headers,
          body: req.args.body
        };
      };
    "
  },
  "response_transform": {
    "code": "
      module.exports = async function (req) {
        // Do something with req.configuration.SERVICE_API_KEY

        return {
          headers: req.args.headers,
          body: req.args.body
        };
      };
    "
  },
  "configuration": {
    "SERVICE_API_KEY": "key_abcd1234"
  },
  "application_id": "45c124e7-6ab2-4899-b4d9-1388b0ba9d04",
  "require_auth": true,
  "created_by": "3ce0dceb-fd0b-4471-8006-c51243c9ef7a",
  "created_at": "2020-09-15T15:53:00+00:00"
}

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

Creates a new Proxy for the Tenant.

Permissions

proxy:create

Request Parameters

Attribute	Required	Type	Default	Description
`name`	true	string	`null`	The name of the Proxy. Has a maximum length of `200`
`destination_url`	true	string	`null`	The URL to proxy requests to
`request_transform`	false	Proxy Transform	`null`	Transform code which will be executed against the proxy's request before sending to the destination.
`response_transform`	false	Proxy Transform	`null`	Transform code which will be executed against the destination's response before returning the proxy response.
`application`	false	Application	`null`	This Application's API key is injected into a pre-configured Node.js BasisTheory instance passed into the Proxy Transform runtime.
`configuration`	false	map	`null`	A key-value map of all configuration name and values for a Proxy Transform
`require_auth`	false	boolean	`true`	Require a `BT-API-KEY` request header for authentication and authorization

Response

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

List Proxies

Request

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

import { BasisTheory } from '@basis-theory/basis-theory-js';

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

const proxies = await bt.proxies.list();

using BasisTheory.net.Proxies;

var client = new ProxyClient("key_N88mVGsp3sCXkykyN2EFED");

var proxies = await client.GetAsync();

import basistheory
from basistheory.api import proxies_api

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="key_N88mVGsp3sCXkykyN2EFED")) as api_client:
    proxy_client = proxies_api.ProxiesApi(api_client)

    proxies = proxy_client.get()

package main

import (
  "context"
  "github.com/Basis-Theory/basistheory-go/v3"
)

func main() {
  configuration := basistheory.NewConfiguration()
  apiClient := basistheory.NewAPIClient(configuration)
  contextWithAPIKey := context.WithValue(context.Background(), basistheory.ContextAPIKeys, map[string]basistheory.APIKey{
    "ApiKey": {Key: "key_N88mVGsp3sCXkykyN2EFED"},
  })

  proxies, httpResponse, err := apiClient.ProxiesApi.Get(contextWithAPIKey).Execute()
}

Response

{
  "pagination": {...}
  "data": [
    {
      "id": "433013a6-a614-4e1e-b2aa-5fba67aa85e6",
      "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
      "name": "My Proxy",
      "key": "e29a50980ca5",
      "destination_url": "https://example.com/api",
      "request_transform": {
        "code": "
          module.exports = async function (req) {
            // Do something with req.configuration.SERVICE_API_KEY

            return {
              headers: req.args.headers,
              body: req.args.body
            };
          };
        "
      },
      "response_transform": {
        "code": "
          module.exports = async function (req) {
            // Do something with req.configuration.SERVICE_API_KEY

            return {
              headers: req.args.headers,
              body: req.args.body
            };
          };
        "
      },
      "configuration": {
        "SERVICE_API_KEY": "key_abcd1234"
      },
      "application_id": "45c124e7-6ab2-4899-b4d9-1388b0ba9d04",
      "require_auth": true,
      "created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
      "created_at": "2020-09-15T15:53:00+00:00",
      "modified_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
      "modified_at": "2021-03-01T08:23:14+00:00"
    },
    {...},
    {...}
  ]
}

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

Get a list of proxies for the Tenant.

Permissions

proxy:read

Query Parameters

Parameter	Required	Type	Default	Description
`id`	false	array	`[]`	An optional list of Proxy ID's to filter the list of proxies by
`name`	false	string	`null`	Wildcard search of proxies by name

Response

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

Get a Proxy

Request

curl "https://api.basistheory.com/proxies/5b493235-6917-4307-906a-2cd6f1a90b13" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED"

import { BasisTheory } from '@basis-theory/basis-theory-js';

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

const proxy = await bt.proxies.retrieve('5b493235-6917-4307-906a-2cd6f1a90b13');

using BasisTheory.net.Proxies;

var client = new ProxyClient("key_N88mVGsp3sCXkykyN2EFED");

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

import basistheory
from basistheory.api import proxies_api

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="key_N88mVGsp3sCXkykyN2EFED")) as api_client:
    proxy_client = proxies_api.ProxiesApi(api_client)

    application = proxy_client.get_by_id("5b493235-6917-4307-906a-2cd6f1a90b13")

package main

import (
  "context"
  "github.com/Basis-Theory/basistheory-go/v3"
)

func main() {
  configuration := basistheory.NewConfiguration()
  apiClient := basistheory.NewAPIClient(configuration)
  contextWithAPIKey := context.WithValue(context.Background(), basistheory.ContextAPIKeys, map[string]basistheory.APIKey{
    "ApiKey": {Key: "key_N88mVGsp3sCXkykyN2EFED"},
  })

  proxy, httpResponse, err := apiClient.ProxiesApi.GetById(contextWithAPIKey, "433013a6-a614-4e1e-b2aa-5fba67aa85e6").Execute()
}

Response

{
  "id": "433013a6-a614-4e1e-b2aa-5fba67aa85e6",
  "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
  "name": "My Proxy",
  "key": "e29a50980ca5",
  "destination_url": "https://example.com/api",
  "request_transform": {
    "code": "
      module.exports = async function (req) {
        // Do something with req.configuration.SERVICE_API_KEY

        return {
          headers: req.args.headers,
          body: req.args.body
        };
      };
    "
  },
  "response_transform": {
    "code": "
      module.exports = async function (req) {
        // Do something with req.configuration.SERVICE_API_KEY

        return {
          headers: req.args.headers,
          body: req.args.body
        };
      };
    "
  },
  "configuration": {
    "SERVICE_API_KEY": "key_abcd1234"
  },
  "application_id": "45c124e7-6ab2-4899-b4d9-1388b0ba9d04",
  "require_auth": true,
  "created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
  "created_at": "2020-09-15T15:53:00+00:00",
  "modified_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
  "modified_at": "2021-03-01T08:23:14+00:00"
}

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

Get a Proxy by ID in the Tenant.

Permissions

proxy:read

URI Parameters

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

Response

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

Update Proxy

Request

curl "https://api.basistheory.com/proxies/433013a6-a614-4e1e-b2aa-5fba67aa85e6" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED" \
  -H "Content-Type: application/json" \
  -X "PUT" \
  -d '{
    "name": "My Proxy",
    "destination_url": "https://example.com/api",
    "request_transform": {
      "code": "
        module.exports = async function (req) {
          // Do something with `req.configuration.SERVICE_API_KEY`

          return {
            headers: req.args.headers,
            body: req.args.body
          };
        };
      "
    },
    "response_transform": {
      "code": "
        module.exports = async function (req) {
          // Do something with `req.configuration.SERVICE_API_KEY`

          return {
            headers: req.args.headers,
            body: req.args.body
          };
        };
      "
    },
    "configuration": {
      "SERVICE_API_KEY": "key_abcd1234"
    },
    "application": {
      "id": "45c124e7-6ab2-4899-b4d9-1388b0ba9d04"
    },
    "require_auth": true
  }'

import { BasisTheory } from '@basis-theory/basis-theory-js';

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

const proxy = await bt.proxies.update('433013a6-a614-4e1e-b2aa-5fba67aa85e6', {
  name: 'My Proxy',
  destinationUrl: 'https://example.com/api',
  requestTransform: {
    code: '
      module.exports = async function (req) {
        // Do something with `req.configuration.SERVICE_API_KEY`

        return {
          headers: req.args.headers,
          body: req.args.body
        };
      };
    '
  },
  responseTransform: {
    code: '
      module.exports = async function (req) {
        // Do something with `req.configuration.SERVICE_API_KEY`

        return {
          headers: req.args.headers,
          body: req.args.body
        };
      };
    '
  },
  configuration: {
    SERVICE_API_KEY: 'key_abcd1234',
  },
  application: {
    id: '45c124e7-6ab2-4899-b4d9-1388b0ba9d04'
  },
  requireAuth: true
});

using BasisTheory.net.Proxies;

var client = new ProxyClient("key_N88mVGsp3sCXkykyN2EFED");

var proxy = await client.UpdateAsync("433013a6-a614-4e1e-b2aa-5fba67aa85e6", 
  new ProxyUpdateRequest {
    Name = "My Proxy",
    DestinationUrl = "https://example.com/api",
    RequestTransform = new RequestTransform {
      Code = @"
        module.exports = async function (req) {
          // Do something with `req.configuration.SERVICE_API_KEY`

          return {
            headers: req.args.headers,
            body: req.args.body
          };
        };
      "
    },
    ResponseTransform = new RequestTransform {
      Code = @"
        module.exports = async function (req) {
          // Do something with `req.configuration.SERVICE_API_KEY`

          return {
            headers: req.args.headers,
            body: req.args.body
          };
        };
      "
    },
    Configuration = new Dictionary<string, string> {
      { "SERVICE_API_KEY", "key_abcd1234" }
    },
    Application = new Application {
      Id = new Guid("45c124e7-6ab2-4899-b4d9-1388b0ba9d04")
    },
    RequireAuthentication = true
  }
);

import basistheory
from basistheory.api import proxies_api
from basistheory.model.update_proxy_request import UpdateProxyRequest

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="key_N88mVGsp3sCXkykyN2EFED")) as api_client:
    proxy_client = proxies_api.ProxiesApi(api_client)

    application = proxy_client.update("433013a6-a614-4e1e-b2aa-5fba67aa85e6", update_proxy_request=UpdateProxyRequest(
        name="My Proxy",
        destination_url="https://example.com/api",
        requeset_transform=ProxyTransform(
            code=" \
                module.exports = async function (req) { \
                  // Do something with `req.configuration.SERVICE_API_KEY` \

                  "return { \
                    headers: req.args.headers, \
                    body: req.args.body \
                  }; \
                };"
        ),
        response_transform=ProxyTransform(
            code=" \
                module.exports = async function (req) { \
                  // Do something with `req.configuration.SERVICE_API_KEY` \

                  "return { \
                    headers: req.args.headers, \
                    body: req.args.body \
                  }; \
                };"
        ),
        configuration={
            "SERVICE_API_KEY": "key_abcd134"
        },
        application=Application(
            id="45c124e7-6ab2-4899-b4d9-1388b0ba9d04"
        ),
        require_auth=True
    ))

package main

import (
  "context"
  "github.com/Basis-Theory/basistheory-go/v3"
)

func main() {
  configuration := basistheory.NewConfiguration()
  apiClient := basistheory.NewAPIClient(configuration)
  contextWithAPIKey := context.WithValue(context.Background(), basistheory.ContextAPIKeys, map[string]basistheory.APIKey{
    "ApiKey": {Key: "key_N88mVGsp3sCXkykyN2EFED"},
  })

  updateProxyRequest := *basistheory.NewUpdateProxyRequest("My Proxy", "https://example.com/api")
  requestTransform := *basistheory.NewProxyTransform()
  requestTransform.SetCode(`
    module.exports = async function (req) {
      // Do something with req.configuration.SERVICE_API_KEY

      return {
        headers: req.args.headers,
        body: req.args.body
      };
    };
  `)
  updateProxyRequest.SetRequestTransform(requestTransform)
  responseTransform := *basistheory.NewProxyTransform()
  responseTransform.SetCode(`
    module.exports = async function (req) {
      // Do something with req.configuration.SERVICE_API_KEY

      return {
        headers: req.args.headers,
        body: req.args.body
      };
    };
  `)
  updateProxyRequest.SetResponseTransform(responseTransform)
  updateProxyRequest.SetConfiguration(map[string]string{
    "SERVICE_API_KEY": "key_abcd134",
  })
  application := *basistheory.NewApplication()
  application.SetId("45c124e7-6ab2-4899-b4d9-1388b0ba9d04")
  updateProxyRequest.SetApplication(application)
  updateProxyRequest.SetRequireAuth(true)

  proxy, httpResponse, err := apiClient.ProxiesApi.Update(contextWithAPIKey, "433013a6-a614-4e1e-b2aa-5fba67aa85e6").UpdateProxyRequest(updateProxyRequest).Execute()
}

Response

{

  "id": "433013a6-a614-4e1e-b2aa-5fba67aa85e6",
  "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
  "name": "My Proxy",
  "key": "e29a50980ca5",
  "destination_url": "https://example.com/api",
  "request_transform": {
    "code": "
      module.exports = async function (req) {
        // Do something with req.configuration.SERVICE_API_KEY

        return {
          headers: req.args.headers,
          body: req.args.body
        };
      };
    "
  },
  "response_transform": {
    "code": "
      module.exports = async function (req) {
        // Do something with req.configuration.SERVICE_API_KEY

        return {
          headers: req.args.headers,
          body: req.args.body
        };
      };
    "
  },
  "configuration": {
    "SERVICE_API_KEY": "key_abcd1234"
  },
  "application_id": "45c124e7-6ab2-4899-b4d9-1388b0ba9d04",
  "require_auth": true,
  "created_by": "3ce0dceb-fd0b-4471-8006-c51243c9ef7a",
  "created_at": "2020-09-15T15:53:00+00:00",
  "modified_by": "34053374-d721-43d8-921c-5ee1d337ef21",
  "modified_at": "2021-03-01T08:23:14+00:00"
}

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

Update a Proxy by ID in the Tenant.

Permissions

proxy:update

URI Parameters

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

Request Parameters

Attribute	Required	Type	Default	Description
`name`	true	string	`null`	The name of the Proxy. Has a maximum length of `200`
`destination_url`	true	string	`null`	The URL to proxy requests to
`request_transform`	false	Proxy Transform	`null`	Transform code which will be executed against the proxy's request before sending to the destination.
`response_transform`	false	Proxy Transform	`null`	Transform code which will be executed against the destination's response before returning the proxy response.
`application`	false	Application	`null`	This Application's API key is injected into a pre-configured Node.js BasisTheory instance passed into the Proxy Transform runtime.
`configuration`	false	map	`null`	A key-value map of all configuration name and values for a Proxy Transform
`require_auth`	false	boolean	`true`	Require a `BT-API-KEY` request header for authentication and authorization

Response

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

Delete Proxy

Request

curl "https://api.basistheory.com/proxies/433013a6-a614-4e1e-b2aa-5fba67aa85e6" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED" \
  -X "DELETE"

import { BasisTheory } from '@basis-theory/basis-theory-js';

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

await bt.proxies.delete('433013a6-a614-4e1e-b2aa-5fba67aa85e6');

using BasisTheory.net.Proxies;

var client = new ProxyClient("key_N88mVGsp3sCXkykyN2EFED");

await client.DeleteAsync("433013a6-a614-4e1e-b2aa-5fba67aa85e6");

import basistheory
from basistheory.api import proxies_api

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="key_N88mVGsp3sCXkykyN2EFED")) as api_client:
    proxies_client = proxies_api.ProxiesApi(api_client)

    proxies_client.delete("433013a6-a614-4e1e-b2aa-5fba67aa85e6")

package main

import (
  "context"
  "github.com/Basis-Theory/basistheory-go/v3"
)

func main() {
  configuration := basistheory.NewConfiguration()
  apiClient := basistheory.NewAPIClient(configuration)
  contextWithAPIKey := context.WithValue(context.Background(), basistheory.ContextAPIKeys, map[string]basistheory.APIKey{
    "ApiKey": {Key: "key_N88mVGsp3sCXkykyN2EFED"},
  })

  httpResponse, err := apiClient.ProxiesApi.Delete(contextWithAPIKey, "433013a6-a614-4e1e-b2aa-5fba67aa85e6").Execute()
}

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

Delete a Proxy by ID in the Tenant.

Permissions

proxy:delete

URI Parameters

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

Response

Returns an error if the Proxy 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`	string	The name of the Reactor Formula. Has a maximum length of `200`
`description`	string	The description of the Reactor Formula
`type`	string	Type of the Reactor Formula
`status`	string	Status of the Reactor Formula
`icon`	string	Base64 data URL of the image
`code`	string	Reactor Formula code which will be executed when the Reactor Formula is processed
`configuration`	array	Array of configuration options for configuring a reactor
`request_parameters`	array	Array of request parameters which will be passed when executing the reactor
`created_at`	date	(Optional) Created date of the Reactor Formula in ISO 8601 format
`created_by`	uuid	(Optional) The ID of the user or Application that created the Reactor Formula
`modified_at`	date	(Optional) Last modified date of the Reactor Formula in ISO 8601 format
`modified_by`	uuid	(Optional) The ID of the user or Application that last modified the Reactor Formula

Reactor Formula Configuration

The configuration property of a Reactor Formula defines the contract that the configuration property must satisfy on all Reactors created from this formula. Elements of a Reactor Formula's configuration array have the following schema:

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

Reactor configuration is intended for properties that can be defined once per Reactor and do not change between Reactor invocations. Complex nested objects (dot-separated names) are not currently supported within a Reactor's configuration.

Reactor Formula Request Parameters

The request_parameters array on a Reactor Formula defines the contract that the args property must satisfy on each request when Invoking a Reactor. Elements of a Reactor Formula's request_parameters array have the following schema:

Attribute	Required	Type	Default	Description
`name`	true	string	`null`	Name of the request parameter. Complex objects can be denoted as `[parent].[child]`
`description`	false	string	`null`	Description of the request parameter
`type`	true	string	`null`	Data type of the request parameter. Valid values are `string`, `boolean`, and `number`
`optional`	false	boolean	`false`	If the request parameter is optional when executing the reactor

Request parameters are intended to define any parameters that will be provided to a Reactor at request-time, and may change across Reactor invocations. Complex objects properties can be passed within the args property to a Reactor, and they can be defined by dot-separating levels of the object hierarchy.

Any args property not associated with a request parameter is still forwarded to the reactor. This allows you to provide complete complex objects including arrays, in which no type checking is applied. For instance, if no request parameters are declared, it means you can provide any payload when invoking the reactor.

For example, to pass a card object whose schema matches the Card Object stored within an Atomic Card token and an array of any type, a Reactor Formula should define the following request parameters:

name	type	optional
`card.number`	string	false
`card.expiration_month`	number	false
`card.expiration_year`	number	false
`card.cvc`	string	true

As you can see, only the primitive typed request parameters are defined. You could even omit them completely and they would still be forwarded to the Reactor and no validation would be applied.

Reactor Formula Code

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

Reactor Formula Request Object

Attribute	Type	Description
`args`	object	The arguments that were provided when the reactor was invoked
`configuration`	object	The configuration defined for the Reactor object

Reactor Formula Response Object

Attribute	Type	Description
`raw`	object	(Optional) Raw output returned from the Reactor
`tokenize`	object	(Optional) A payload that will be tokenized to produce one or more tokens

The payload returned in the tokenize property will be tokenized in the same way that requests are tokenized via the Tokenize endpoint. For more information, see Tokenize.

Reactor Formula Code is written in Javascript (targeting Node.js v16) and generally follows the structure:

module.exports = async function (req) {
  const { my_arg } = req.args; // access any args provided with the request
  const { MY_CONFIG } = req.configuration; // access any static config defined on the Reactor

  // do anything here!

  return {
      raw: {}, // non-sensitive data that should be returned in plaintext
      tokenize: {} // sensitive data that should be tokenized
  };
};

For more information about writing your own code for a Reactor Formula, check out our guide.

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

Reactor Formula Statuses

Type	Description
`verified`	The formula has been verified and is generally available
`coming_soon`	The formula has limited availability. Request to join the Private Beta for access.

Create Reactor Formula

Request

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

        return {
          raw: {
            foo: 'bar'
          }
        };
      };
    ",
    "configuration": [
      {
        "name": "SERVICE_API_KEY",
        "description": "Configuration description",
        "type": "string"
      }
    ],
    "request_parameters": [
      {
        "name": "request_parameter_1",
        "description": "Request parameter description",
        "type": "string"
      },
      {
        "name": "request_parameter_2",
        "description": "Request parameter description",
        "type": "boolean",
        "optional": true
      }
    ]
  }'

import { BasisTheory } from '@basis-theory/basis-theory-js';

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

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

      return {
        raw: {
          foo: 'bar'
        }
      };
    };
  ',
  configuration: [
    {
      name: 'SERVICE_API_KEY',
      description: 'Configuration description',
      type: 'string',
    },
  ],
  requestParameters: [
    {
      name: 'request_parameter_1',
      description: 'Request parameter description',
      type: 'string',
    },
    {
      name: 'request_parameter_2',
      description: 'Request parameter description',
      type: 'boolean',
      optional: true
    }
  ],
});

using BasisTheory.net.ReactorFormulas;

var client = new ReactorFormulaClient("key_N88mVGsp3sCXkykyN2EFED");

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

      return {
        raw: {
          foo: 'bar'
        }
      };
    };
  ",
  Configuration = new List<ReactorFormulaConfiguration> {
    new ReactorFormulaConfiguration {
      Name = "SERVICE_API_KEY",
      Description = "Configuration description",
      Type = "string"
    }
  },
  RequestParameters = new List<ReactorFormulaRequestParameter> {
    new ReactorFormulaRequestParameter {
      Name = "request_parameter_1",
      Description = "Request parameter description",
      Type = "string"
    },
    new ReactorFormulaRequestParameter {
      Name = "request_parameter_2",
      Description = "Request parameter description",
      Type = "boolean",
      IsOptional = true
    }
  }
});

import basistheory
from basistheory.api import reactor_formulas_api
from basistheory.model.create_reactor_formula_request import CreateReactorFormulaRequest
from basistheory.model.reactor_formula_configuration import ReactorFormulaConfiguration
from basistheory.model.reactor_formula_request_parameter import ReactorFormulaRequestParameter

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="key_N88mVGsp3sCXkykyN2EFED")) as api_client:
    reactor_formulas_client = reactor_formulas_api.ReactorFormulasApi(
        api_client)

    reactor_formula = reactor_formulas_client.create(create_reactor_formula_request=CreateReactorFormulaRequest(
        name="My Private Reactor",
        description="Securely exchange token for another token",
        type="private",
        icon="data:image/png;base64, iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==",
        code=" \
            module.exports = async function (req) { \
                // Do something with `req.configuration.SERVICE_API_KEY`" \

                "return { \
                    raw: { \
                        foo: 'bar' \
                    } \
                }; \
            };",
        configuration=[
            ReactorFormulaConfiguration(
                name="SERVICE_API_KEY",
                description="Configuration description",
                type="string"
            )
        ],
        request_parameters=[
            ReactorFormulaRequestParameter(
                name="request_parameter_1",
                description="Request parameter description",
                type="string"
            ),
            ReactorFormulaRequestParameter(
                name="request_parameter_2",
                description="Request parameter description",
                type="boolean",
                optional=True
            )
        ]
    ))

package main

import (
  "context"
  "github.com/Basis-Theory/basistheory-go/v3"
)

func main() {
  configuration := basistheory.NewConfiguration()
  apiClient := basistheory.NewAPIClient(configuration)
  contextWithAPIKey := context.WithValue(context.Background(), basistheory.ContextAPIKeys, map[string]basistheory.APIKey{
    "ApiKey": {Key: "key_N88mVGsp3sCXkykyN2EFED"},
  })

  createReactorFormulaRequest := *basistheory.NewCreateReactorFormulaRequest("private", "My Private Reactor")
  createReactorFormulaRequest.SetDescription("Securely exchange token for another token")
  createReactorFormulaRequest.SetIcon("data:image/png;base64, iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==")
  createReactorFormulaRequest.SetCode(`
    module.exports = async function (req) {
      // Do something with req.configuration.SERVICE_API_KEY

      return {
      raw: {
        foo: 'bar'
      }
      };
    };
  `)
  var configurations []basistheory.ReactorFormulaConfigurationModel
  reactorFormulaConfiguration := *basistheory.NewReactorFormulaConfiguration("SERVICE_API_KEY", "string")
  reactorFormulaConfiguration.SetDescription("Configuration description")
  configurations = append(configurations, reactorFormulaConfiguration)
  createReactorFormulaRequest.SetConfiguration(configurations)
  var requestParameters []basistheory.ReactorFormulaRequestParameterModel
  reactorFormulaRequestParameter1 := *basistheory.NewReactorFormulaRequestParameter("request_parameter_1", "string")
  reactorFormulaRequestParameter1.SetDescription("Request parameter description")
  requestParameters = append(requestParameters, reactorFormulaRequestParameter1)
  reactorFormulaRequestParameter2 := *basistheory.NewReactorFormulaRequestParameter("request_parameter_2", "boolean")
  reactorFormulaRequestParameter2.SetDescription("Request parameter description")
  reactorFormulaRequestParameter2.SetOptional(true)
  requestParameters = append(requestParameters, reactorFormulaRequestParameter2)
  createReactorFormulaRequest.SetRequestParameters(requestParameters)

  reactorFormula, httpResponse, err := apiClient.ReactorFormulasApi.Create(contextWithAPIKey).CreateReactorFormulaRequest(createReactorFormulaRequest).Execute()
}

Response

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

      return {
        raw: {
          foo: 'bar',
        }
      };
    };
  ",
  "configuration": [
    {
      "name": "SERVICE_API_KEY",
      "description": "Configuration description",
      "type": "string"
    }
  ],
  "request_parameters": [
    {
      "name": "request_parameter_1",
      "description": "Request parameter description",
      "type": "string"
    },
    {
      "name": "request_parameter_2",
      "description": "Request parameter description",
      "type": "boolean",
      "optional": true
    }
  ],
  "created_by": "c57a0d0d-e8e6-495f-9c79-a317cc21996c",
  "created_at": "2020-09-15T15:53:00+00:00"
}

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

Create a new Reactor Formula for the Tenant.

Permissions

reactor:create

Request Parameters

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

Response

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

List Reactor Formulas

Request

curl "https://api.basistheory.com/reactor-formulas" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED"

import { BasisTheory } from '@basis-theory/basis-theory-js';

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

const reactorFormulas = await bt.reactorFormulas.list();

using BasisTheory.net.ReactorFormulas;

var client = new ReactorFormulaClient("key_N88mVGsp3sCXkykyN2EFED");

var reactorFormulas = await client.GetAsync();

import basistheory
from basistheory.api import reactor_formulas_api

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="key_N88mVGsp3sCXkykyN2EFED")) as api_client:
    reactor_formulas_client = reactor_formulas_api.ReactorFormulasApi(
        api_client)

    reactor_formulas = reactor_formulas_client.get()

package main

import (
  "context"
  "github.com/Basis-Theory/basistheory-go/v3"
)

func main() {
  configuration := basistheory.NewConfiguration()
  apiClient := basistheory.NewAPIClient(configuration)
  contextWithAPIKey := context.WithValue(context.Background(), basistheory.ContextAPIKeys, map[string]basistheory.APIKey{
    "ApiKey": {Key: "key_N88mVGsp3sCXkykyN2EFED"},
  })

  reactorFormulas, httpResponse, err := apiClient.ReactorFormulasApi.Get(contextWithAPIKey).Execute()
}

Response

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

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

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

Get a list of official Reactor Formulas 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

Response

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

Get a Reactor Formula

Request

curl "https://api.basistheory.com/reactor-formulas/17069df1-80f4-439e-86a7-4121863e4678" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED"

import { BasisTheory } from '@basis-theory/basis-theory-js';

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

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

using BasisTheory.net.ReactorFormulas;

var client = new ReactorFormulaClient("key_N88mVGsp3sCXkykyN2EFED");

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

import basistheory
from basistheory.api import reactor_formulas_api

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="key_N88mVGsp3sCXkykyN2EFED")) as api_client:
    reactor_formulas_client = reactor_formulas_api.ReactorFormulasApi(
        api_client)

    reactor_formula = reactor_formulas_client.get_by_id("17069df1-80f4-439e-86a7-4121863e4678")

package main

import (
  "context"
  "github.com/Basis-Theory/basistheory-go/v3"
)

func main() {
  configuration := basistheory.NewConfiguration()
  apiClient := basistheory.NewAPIClient(configuration)
  contextWithAPIKey := context.WithValue(context.Background(), basistheory.ContextAPIKeys, map[string]basistheory.APIKey{
    "ApiKey": {Key: "key_N88mVGsp3sCXkykyN2EFED"},
  })

  reactorFormula, httpResponse, err := apiClient.ReactorFormulasApi.GetById(contextWithAPIKey, "17069df1-80f4-439e-86a7-4121863e4678").Execute()
}

Response

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

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

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

Get a Reactor Formula by ID in the Tenant.

Permissions

reactor:read

URI Parameters

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

Response

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

Update Reactor Formula

Request

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

        return {
          raw: {
            foo: 'bar'
          }
        };
      };
    ",
    "configuration": [
      {
        "name": "SERVICE_API_KEY",
        "description": "Configuration description",
        "type": "string"
      }
    ],
    "request_parameters": [
      {
        "name": "request_parameter_1",
        "description": "Request parameter description",
        "type": "string"
      },
      {
        "name": "request_parameter_2",
        "description": "Request parameter description",
        "type": "boolean",
        "optional": true
      }
    ]
  }'

import { BasisTheory } from '@basis-theory/basis-theory-js';

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

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

      return {
        raw: {
          foo: 'bar',
        }
      };
    };
  ',
  configuration: [
    {
      name: 'SERVICE_API_KEY',
      description: 'Configuration description',
      type: 'string',
    },
  ],
  requestParameters: [
    {
      name: 'request_parameter_1',
      description: 'Request parameter description',
      type: 'string',
    },
    {
      name: 'request_parameter_2',
      description: 'Request parameter description',
      type: 'boolean',
      optional: true
    }
  ],
});

using BasisTheory.net.ReactorFormulas;

var client = new ReactorFormulaClient("key_N88mVGsp3sCXkykyN2EFED");

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

        return {
          raw: {
            foo: 'bar'
          }
        };
      };
    ",
    Configuration = new List<ReactorFormulaConfiguration> {
      new ReactorFormulaConfiguration {
        Name = "SERVICE_API_KEY",
        Description = "Configuration description",
        Type = "string"
      }
    },
    RequestParameters = new List<ReactorFormulaRequestParameter> {
      new ReactorFormulaRequestParameter {
        Name = "request_parameter_1",
        Description = "Request parameter description",
        Type = "string"
      },
      new ReactorFormulaRequestParameter {
        Name = "request_parameter_2",
        Description = "Request parameter description",
        Type = "boolean",
        IsOptional = true
      }
    }
  }
);

import basistheory
from basistheory.api import reactor_formulas_api
from basistheory.model.update_reactor_formula_request import UpdateReactorFormulaRequest
from basistheory.model.reactor_formula_configuration import ReactorFormulaConfiguration
from basistheory.model.reactor_formula_request_parameter import ReactorFormulaRequestParameter

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="key_N88mVGsp3sCXkykyN2EFED")) as api_client:
    reactor_formulas_client = reactor_formulas_api.ReactorFormulasApi(
        api_client)

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

                "return { \
                    raw: { \
                        foo: 'bar' \
                    } \
                }; \
            };",
        configuration=[
            ReactorFormulaConfiguration(
                name="SERVICE_API_KEY",
                description="Configuration description",
                type="string"
            )
        ],
        request_parameters=[
            ReactorFormulaRequestParameter(
                name="request_parameter_1",
                description="Request parameter description",
                type="string"
            ),
            ReactorFormulaRequestParameter(
                name="request_parameter_2",
                description="Request parameter description",
                type="boolean",
                optional=True
            )
        ]
    ))

package main

import (
  "context"
  "github.com/Basis-Theory/basistheory-go/v3"
)

func main() {
  configuration := basistheory.NewConfiguration()
  apiClient := basistheory.NewAPIClient(configuration)
  contextWithAPIKey := context.WithValue(context.Background(), basistheory.ContextAPIKeys, map[string]basistheory.APIKey{
    "ApiKey": {Key: "key_N88mVGsp3sCXkykyN2EFED"},
  })

  updateReactorFormulaRequest := *basistheory.NewUpdateReactorFormulaRequest("private", "My Private Reactor")
  updateReactorFormulaRequest.SetDescription("Securely exchange token for another token")
  updateReactorFormulaRequest.SetIcon("data:image/png;base64, iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==")
  updateReactorFormulaRequest.SetCode(`
    module.exports = async function (req) {
      // Do something with req.configuration.SERVICE_API_KEY

      return {
      raw: {
        foo: 'bar'
      }
      };
    };
  `)

  var configurations []basistheory.ReactorFormulaConfigurationModel
  reactorFormulaConfiguration := *basistheory.NewReactorFormulaConfiguration("SERVICE_API_KEY", "string")
  reactorFormulaConfiguration.SetDescription("Configuration description")
  configurations = append(configurations, reactorFormulaConfiguration)
  updateReactorFormulaRequest.SetConfiguration(configurations)
  var requestParameters []basistheory.ReactorFormulaRequestParameterModel
  reactorFormulaRequestParameter1 := *basistheory.NewReactorFormulaRequestParameter("request_parameter_1", "string")
  reactorFormulaRequestParameter1.SetDescription("Request parameter description")
  requestParameters = append(requestParameters, reactorFormulaRequestParameter1)
  reactorFormulaRequestParameter2 := *basistheory.NewReactorFormulaRequestParameter("request_parameter_2", "boolean")
  reactorFormulaRequestParameter2.SetDescription("Request parameter description")
  reactorFormulaRequestParameter2.SetOptional(true)
  requestParameters = append(requestParameters, reactorFormulaRequestParameter2)
  updateReactorFormulaRequest.SetRequestParameters(requestParameters)

  reactorFormula, httpResponse, err := apiClient.ReactorFormulasApi.Update(contextWithAPIKey, "17069df1-80f4-439e-86a7-4121863e4678").UpdateReactorFormulaRequest(updateReactorFormulaRequest).Execute()
}

Response

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

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

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

Update a Reactor Formula by ID in the Tenant.

Permissions

reactor:update

URI Parameters

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

Request Parameters

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

Response

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

Delete Reactor Formula

Request

curl "https://api.basistheory.com/reactor-formulas/17069df1-80f4-439e-86a7-4121863e4678" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED" \
  -X "DELETE"

import { BasisTheory } from '@basis-theory/basis-theory-js';

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

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

using BasisTheory.net.ReactorFormulas;

var client = new ReactorFormulaClient("key_N88mVGsp3sCXkykyN2EFED");

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

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="key_N88mVGsp3sCXkykyN2EFED")) as api_client:
    reactor_formulas_client = reactor_formulas_api.ReactorFormulasApi(
        api_client)

    reactor_formulas = reactor_formulas_client.delete("17069df1-80f4-439e-86a7-4121863e4678")

package main

import (
  "context"
  "github.com/Basis-Theory/basistheory-go/v3"
)

func main() {
  configuration := basistheory.NewConfiguration()
  apiClient := basistheory.NewAPIClient(configuration)
  contextWithAPIKey := context.WithValue(context.Background(), basistheory.ContextAPIKeys, map[string]basistheory.APIKey{
    "ApiKey": {Key: "key_N88mVGsp3sCXkykyN2EFED"},
  })

  httpResponse, err := apiClient.ReactorFormulasApi.Delete(contextWithAPIKey, "17069df1-80f4-439e-86a7-4121863e4678").Execute()
}

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

Delete a Reactor Formula by ID in the Tenant.

Permissions

reactor:delete

URI Parameters

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

Response

Returns an error if the Reactor Formula failed to delete.

Reactors

Reactor Object

Attribute	Type	Description
`id`	uuid	Unique identifier of the Reactor which can be used to get a Reactor
`tenant_id`	uuid	The Tenant ID which owns the reactor
`name`	string	The name of the reactor
`formula`	Reactor Formula	Reactor Formula this Reactor is configured for
`configuration`	map	A key-value map of all configuration name and values for a Reactor Formula configuration
`application`	Application	(Optional) This Application's API key is injected into a pre-configured Node.js BasisTheory instance passed into the Reactor's runtime.
`created_by`	uuid	(Optional) The ID of the user or Application that created the Reactor
`created_at`	string	(Optional) Created date of the Reactor in ISO 8601 format
`modified_by`	uuid	(Optional) The ID of the user or Application that last modified the Reactor
`modified_at`	date	(Optional) Last modified date of the Reactor in ISO 8601 format

Create Reactor

Request

curl "https://api.basistheory.com/reactors" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED" \
  -H "Content-Type: application/json" \
  -X "POST" \
  -d '{
    "name": "My Reactor",
    "configuration": {
      "SERVICE_API_KEY": "key_abcd1234"
    },
    "formula": {
      "id": "17069df1-80f4-439e-86a7-4121863e4678"
    },
    "application": {
      "id": "45c124e7-6ab2-4899-b4d9-1388b0ba9d04"
    }
  }'

import { BasisTheory } from '@basis-theory/basis-theory-js';

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

const reactor = await bt.reactors.create({
  name: 'My Reactor',
  configuration: {
    SERVICE_API_KEY: 'key_abcd1234',
  },
  formula: {
    id: '17069df1-80f4-439e-86a7-4121863e4678',
  },
  application: {
    id: '45c124e7-6ab2-4899-b4d9-1388b0ba9d04'
  }
});

using BasisTheory.net.Reactors;

var client = new ReactorClient("key_N88mVGsp3sCXkykyN2EFED");

var reactor = await client.CreateAsync(new Reactor {
  Name = "My Reactor",
  Configuration = new Dictionary<string, string> {
    { "SERVICE_API_KEY", "key_abcd1234" }
  },
  Formula = new Formula {
    Id = new Guid("17069df1-80f4-439e-86a7-4121863e4678")
  },
  Application = new Application {
    Id = new Guid("45c124e7-6ab2-4899-b4d9-1388b0ba9d04")
  }
});

import basistheory
from basistheory.api import reactors_api
from basistheory.model.create_reactor_request import CreateReactorRequest
from basistheory.model.reactor_formula import ReactorFormula
from basistheory.model.application import Application

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="key_N88mVGsp3sCXkykyN2EFED")) as api_client:
    reactors_client = reactors_api.ReactorsApi(api_client)

    reactor = reactors_client.create(create_reactor_request=CreateReactorRequest(
        name="My Reactor",
        configuration={
            "SERVICE_API_KEY": "key_abcd134"
        },
        formula=ReactorFormula(
            id="17069df1-80f4-439e-86a7-4121863e4678"
        ),
        application=Application(
            id="45c124e7-6ab2-4899-b4d9-1388b0ba9d04"
        )
    ))

package main

import (
  "context"
  "github.com/Basis-Theory/basistheory-go/v3"
)

func main() {
  configuration := basistheory.NewConfiguration()
  apiClient := basistheory.NewAPIClient(configuration)
  contextWithAPIKey := context.WithValue(context.Background(), basistheory.ContextAPIKeys, map[string]basistheory.APIKey{
    "ApiKey": {Key: "key_N88mVGsp3sCXkykyN2EFED"},
  })

  createReactorRequest := *basistheory.NewCreateReactorRequest("My Reactor")
  createReactorRequest.SetConfiguration(map[string]string{
    "SERVICE_API_KEY": "key_abcd134",
  })
  reactorFormula := *basistheory.NewReactorFormula()
  reactorFormula.SetId("17069df1-80f4-439e-86a7-4121863e4678")
  createReactorRequest.SetFormula(reactorFormula)
  application := *basistheory.NewApplication()
  application.SetId("45c124e7-6ab2-4899-b4d9-1388b0ba9d04")
  createReactorRequest.SetApplication(application)

  reactor, httpResponse, error := apiClient.ReactorsApi.Create(contextWithAPIKey).CreateReactorRequest(createReactorRequest).Execute()
}

Response

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

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

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

Permissions

reactor:create

Request Parameters

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

The configuration object must satisfy the name and type constraints defined by the Reactor Formula's configuration property.

Response

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

List Reactors

Request

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

import { BasisTheory } from '@basis-theory/basis-theory-js';

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

const reactors = await bt.reactors.list();

using BasisTheory.net.Reactors;

var client = new ReactorClient("key_N88mVGsp3sCXkykyN2EFED");

var reactors = await client.GetAsync();

import basistheory
from basistheory.api import reactors_api

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="key_N88mVGsp3sCXkykyN2EFED")) as api_client:
    reactors_client = reactors_api.ReactorsApi(api_client)

    reactors = reactors_client.get()

package main

import (
  "context"
  "github.com/Basis-Theory/basistheory-go/v3"
)

func main() {
  configuration := basistheory.NewConfiguration()
  apiClient := basistheory.NewAPIClient(configuration)
  contextWithAPIKey := context.WithValue(context.Background(), basistheory.ContextAPIKeys, map[string]basistheory.APIKey{
    "ApiKey": {Key: "key_N88mVGsp3sCXkykyN2EFED"},
  })

  reactors, httpResponse, err := apiClient.ReactorsApi.Get(contextWithAPIKey).Execute()
}

Response

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

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

Get a list of reactors for the Tenant.

Permissions

reactor:read

Query Parameters

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

Response

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

Get a Reactor

Request

curl "https://api.basistheory.com/reactors/5b493235-6917-4307-906a-2cd6f1a90b13" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED"

import { BasisTheory } from '@basis-theory/basis-theory-js';

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

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

using BasisTheory.net.Reactors;

var client = new ReactorClient("key_N88mVGsp3sCXkykyN2EFED");

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

import basistheory
from basistheory.api import reactors_api

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="key_N88mVGsp3sCXkykyN2EFED")) as api_client:
    reactors_client = reactors_api.ReactorsApi(api_client)

    reactor = reactors_client.get_by_id("5b493235-6917-4307-906a-2cd6f1a90b13")

package main

import (
  "context"
  "github.com/Basis-Theory/basistheory-go/v3"
)

func main() {
  configuration := basistheory.NewConfiguration()
  apiClient := basistheory.NewAPIClient(configuration)
  contextWithAPIKey := context.WithValue(context.Background(), basistheory.ContextAPIKeys, map[string]basistheory.APIKey{
    "ApiKey": {Key: "key_N88mVGsp3sCXkykyN2EFED"},
  })

  reactor, httpResponse, err := apiClient.ReactorsApi.GetById(contextWithAPIKey, "5b493235-6917-4307-906a-2cd6f1a90b13").Execute()
}

Response

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

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

Get a Reactor by ID in the Tenant.

Permissions

reactor:read

URI Parameters

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

Response

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

Update Reactor

Request

curl "https://api.basistheory.com/reactors/5b493235-6917-4307-906a-2cd6f1a90b13" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED" \
  -H "Content-Type: application/json" \
  -X "PUT" \
  -d '{
    "name": "My Reactor",
    "configuration": {
      "SERVICE_API_KEY": "key_abcd1234"
    },
    "application": {
      "id": "45c124e7-6ab2-4899-b4d9-1388b0ba9d04"
    }
  }'

import { BasisTheory } from '@basis-theory/basis-theory-js';

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

const reactor = await bt.reactors.update('5b493235-6917-4307-906a-2cd6f1a90b13', {
  name: 'My Reactor',
  configuration: {
    SERVICE_API_KEY: 'key_abcd1234',
  },
  application: {
    id: '45c124e7-6ab2-4899-b4d9-1388b0ba9d04'
  }
});

using BasisTheory.net.Reactors;

var client = new ReactorClient("key_N88mVGsp3sCXkykyN2EFED");

var reactor = await client.UpdateAsync("5b493235-6917-4307-906a-2cd6f1a90b13", 
  new Reactor {
    Name = "My Reactor",
    Configuration = new Dictionary<string, string> {
      { "SERVICE_API_KEY", "key_abcd1234" }
    },
    Application = new Application {
      Id = new Guid("45c124e7-6ab2-4899-b4d9-1388b0ba9d04")
    }
  }
);

import basistheory
from basistheory.api import reactors_api
from basistheory.model.update_reactor_request import UpdateReactorRequest
from basistheory.model.application import Application

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="key_N88mVGsp3sCXkykyN2EFED")) as api_client:
    reactors_client = reactors_api.ReactorsApi(api_client)

    reactor = reactors_client.update("5b493235-6917-4307-906a-2cd6f1a90b13", update_reactor_request=UpdateReactorRequest(
        name="My Reactor",
        configuration={
            "SERVICE_API_KEY": "key_abcd134"
        },
        application=Application(
            id="45c124e7-6ab2-4899-b4d9-1388b0ba9d04"
        )
    ))

package main

import (
  "context"
  "github.com/Basis-Theory/basistheory-go/v3"
)

func main() {
  configuration := basistheory.NewConfiguration()
  apiClient := basistheory.NewAPIClient(configuration)
  contextWithAPIKey := context.WithValue(context.Background(), basistheory.ContextAPIKeys, map[string]basistheory.APIKey{
    "ApiKey": {Key: "key_N88mVGsp3sCXkykyN2EFED"},
  })

  updateReactorRequest := *basistheory.NewUpdateReactorRequest("My Reactor")
  updateReactorRequest.SetConfiguration(map[string]string{
    "SERVICE_API_KEY": "key_abcd134",
  })
  application := *basistheory.NewApplication()
  application.SetId("45c124e7-6ab2-4899-b4d9-1388b0ba9d04")
  updateReactorRequest.SetApplication(application)

  reactor, httpResponse, err := apiClient.ReactorsApi.Update(contextWithAPIKey, "5b493235-6917-4307-906a-2cd6f1a90b13").UpdateReactorRequest(updateReactorRequest).Execute()
}

Response

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

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

Update a Reactor by ID in the Tenant.

Permissions

reactor:update

URI Parameters

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

Request Parameters

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

Response

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

Delete Reactor

Request

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

import { BasisTheory } from '@basis-theory/basis-theory-js';

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

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

using BasisTheory.net.Reactors;

var client = new ReactorClient("key_N88mVGsp3sCXkykyN2EFED");

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

import basistheory
from basistheory.api import reactors_api

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="key_N88mVGsp3sCXkykyN2EFED")) as api_client:
    reactors_client = reactors_api.ReactorsApi(api_client)

    reactors_client.delete("fb124bba-f90d-45f0-9a59-5edca27b3b4a")

package main

import (
  "context"
  "github.com/Basis-Theory/basistheory-go/v3"
)

func main() {
  configuration := basistheory.NewConfiguration()
  apiClient := basistheory.NewAPIClient(configuration)
  contextWithAPIKey := context.WithValue(context.Background(), basistheory.ContextAPIKeys, map[string]basistheory.APIKey{
    "ApiKey": {Key: "key_N88mVGsp3sCXkykyN2EFED"},
  })

  httpResponse, err := apiClient.ReactorsApi.Delete(contextWithAPIKey, "fb124bba-f90d-45f0-9a59-5edca27b3b4a").Execute()
}

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.

Invoke a Reactor

Request

curl "https://api.basistheory.com/reactors/5b493235-6917-4307-906a-2cd6f1a90b13/react" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED" \
  -H "Content-Type: application/json" \
  -X "POST" \
  -d '{
    "args": {
      "card": "{{fe7c0a36-eb45-4f68-b0a0-791de28b29e4}}",
      "customer_id": "myCustomerId1234"
    }
  }'

import { BasisTheory } from '@basis-theory/basis-theory-js';

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

const reactResponse = await bt.reactors.react('5b493235-6917-4307-906a-2cd6f1a90b13', {
  args: {
    card: '{{fe7c0a36-eb45-4f68-b0a0-791de28b29e4}}',
    customer_id: 'myCustomerId1234',
  },
});

using BasisTheory.net.Reactors;
using BasisTheory.net.Reactors.Requests;

var client = new ReactorClient("key_N88mVGsp3sCXkykyN2EFED");

var reactResponse = await client.ReactAsync("5b493235-6917-4307-906a-2cd6f1a90b13", 
  new ReactRequest {
    Arguments = new {
      card = "{{fe7c0a36-eb45-4f68-b0a0-791de28b29e4}}",
      customer_id = "myCustomerId1234"
    }
  });

import basistheory
from basistheory.api import reactors_api
from basistheory.model.react_request import ReactRequest

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="key_N88mVGsp3sCXkykyN2EFED")) as api_client:
    reactors_client = reactors_api.ReactorsApi(api_client)

    react_response = reactors_client.react("5b493235-6917-4307-906a-2cd6f1a90b13", react_request=ReactRequest(
        args={
          "card":"{{fe7c0a36-eb45-4f68-b0a0-791de28b29e4}}",
          "customer_id": "myCustomerId1234"
        }
    ))

package main

import (
  "context"
  "github.com/Basis-Theory/basistheory-go/v3"
)

func main() {
  configuration := basistheory.NewConfiguration()
  apiClient := basistheory.NewAPIClient(configuration)
  contextWithAPIKey := context.WithValue(context.Background(), basistheory.ContextAPIKeys, map[string]basistheory.APIKey{
    "ApiKey": {Key: "key_N88mVGsp3sCXkykyN2EFED"},
  })

  reactRequest := *basistheory.NewReactRequest()
  reactRequest.SetArgs(map[string]interface{}{
    "card": "{{fe7c0a36-eb45-4f68-b0a0-791de28b29e4}}",
    "customer_id": "myCustomerId1234",
  })

  reacthttpResponse, httpResponse, err := apiClient.ReactorsApi.React(contextWithAPIKey, "5b493235-6917-4307-906a-2cd6f1a90b13").ReactRequest(reactRequest).Execute()
}

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

Invoke a reactor by ID.

Permissions

token:use

The token:use permission is required to use a Reactor, and it is required for each Container of Tokens you wish to detokenize in a Reactor.

URI Parameters

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

Request Parameters

Parameter	Required	Type	Default	Description
`args`	false	object	`null`	Arguments to provide to the reactor. These arguments must contain the declared request parameters for the reactor formula.

Reactor Request Parameters

The reactor will be executed with a req object that contains the following properties

Parameter	Description
`args`	Detokenized arguments to provided to the reactor.
`args.body`	Detokenized request body when executed in the context of a proxy request.
`args.headers`	Request headers when executed in the context of a proxy request.
`configuration`	A key-value map of all configuration name and values when creating the Reactor
`bt`	A pre-configured Basis Theory JS instance for the application defined with the Reactor. This will be `null` if no application was defined.

Response

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

Reactor Response Object

Attribute	Type	Description
`tokens`	object	(Optional) Token(s) created from the `tokenize` block of the Reactor Formula response
`raw`	object	(Optional) Raw output returned from the Reactor
`raw.body`	object	(Required if proxy request) The `body` forwarded to the destination for the proxy request
`raw.headers`	object	(Required if proxy request) The `headers` forwarded to the destination for the proxy request

Validation

When invoking a reactor, the args must satisfy the request_parameters contract declared by the Reactor Formula. The names of properties passed within args must match the names of each of the declared request_parameters - this comparison is case-sensitive. Additional arguments included within args that are not declared as request parameters will be removed from the request.

Nested objects may be passed within args, as long as each sub-property is declared as a request parameter, dot-separating levels of the object hierarchy. For example, we may have a Reactor Formula with complex request parameters declared as:

name	type	optional
`request_id`	string	false
`user.first_name`	string	false
`user.last_name`	string	false
`user.address.city`	string	true
`user.address.state`	string	true

Then the following arguments would constitute a valid Reactor request:

{
  "args": {
    "request_id": "d29e8a27-bfdb-4d26-9f13-29bdeafc9bfe",
    "user": {
      "first_name": "John",
      "last_name": "Doe",
      "address": {
        "city": "Seattle",
        "state": "WA"
      }
    }
  }
}

All required request_parameters must be included within the args on each request. If a request parameter was defined with optional: false and a value for this parameter is not provided within args, the request will be rejected with a 400 error.

Each argument must match the type on the corresponding request parameter, and if the type does not match, auto casting to the declared type will be attempted. For example, say a request parameter is declared with type number but the string value "123" is provided. This value can be cast to a number, so the reactor would receive the numeric value 123. However, if the string value "non-numeric" were provided, a 400 error would be returned because the value cannot be cast to a number.

Detokenization

In order to use tokenized data within a reactor, the args parameter may contain one or more detokenization expressions. When any detokenization expressions are detected, Basis Theory will attempt to detokenize and inject the raw token data into the args forwarded to the Reactor function.

Reactor request args may contain a mixture of detokenization expressions and raw plaintext data.

Tokens containing complex data may be detokenized into a Reactor request, including Bank and Card token types. When tokens with complex data are detokenized, the entire JSON data payload will be included within the args. For an example, see Use Complex Tokens.

If the args passed into a Reactor contain additional properties that have not been declared as request parameters on the Reactor Formula, those properties will be automatically removed and not sent on the request to the Reactor function.

Validation is performed on the resulting request after detokenization, so several required request parameters may be supplied by detokenizing a single complex token that contains several of the request parameters.

At most, 100 tokens may be detokenized within a single Reactor request.

Tenants

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

Tenant Object

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

Tenant Usage Report Object

Attribute	Type	Description
`token_report`	Token Report	Token Usage Report for Tenant

Token Report Object

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

Token Type Metrics Object

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

Tenant Settings Object

Attribute	Type	Description
`deduplicate_tokens`	string	(Bool) Whether tokens are deduplicated on creation and updates

Get a Tenant

Request

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

import { BasisTheory } from '@basis-theory/basis-theory-js';

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

const tenant = await bt.tenants.retrieve();

using BasisTheory.net.Tenants;

var client = new TenantClient("key_N88mVGsp3sCXkykyN2EFED");

var tenant = await client.GetSelfAsync();

import basistheory
from basistheory.api import tenants_api

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="key_N88mVGsp3sCXkykyN2EFED")) as api_client:
    tenants_client = tenants_api.TenantsApi(api_client)

    tenant = tenants_client.get()

package main

import (
  "context"
  "github.com/Basis-Theory/basistheory-go/v3"
)

func main() {
  configuration := basistheory.NewConfiguration()
  apiClient := basistheory.NewAPIClient(configuration)
  contextWithAPIKey := context.WithValue(context.Background(), basistheory.ContextAPIKeys, map[string]basistheory.APIKey{
    "ApiKey": {Key: "key_N88mVGsp3sCXkykyN2EFED"},
  })

  tenant, httpResponse, err := apiClient.TenantsApi.Get(contextWithAPIKey).Execute()
}

Response

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

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

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

Permissions

tenant:read

Response

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

Update Tenant

Request

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

import { BasisTheory } from '@basis-theory/basis-theory-js';

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

const tenant = await bt.tenants.update({
  name: 'My Example Tenant',
  settings: {
    "deduplicate_tokens": "true"
  }
});

using BasisTheory.net.Tenants;

var client = new TenantClient("key_N88mVGsp3sCXkykyN2EFED");

var tenant = await client.UpdateAsync(new Tenant {
  Name = "My Example Tenant"
  Settings = new Dictionary<string, string> {
    { "deduplicate_tokens",  "true" }
  },
});

import basistheory
from basistheory.api import tenants_api
from basistheory.model.update_tenant_request import UpdateTenantRequest

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="key_N88mVGsp3sCXkykyN2EFED")) as api_client:
    tenants_client = tenants_api.TenantsApi(api_client)

    tenant = tenants_client.update(update_tenant_request=UpdateTenantRequest(
        name="My Example Tenant"
    ))

package main

import (
  "context"
  "github.com/Basis-Theory/basistheory-go/v3"
)

func main() {
  configuration := basistheory.NewConfiguration()
  apiClient := basistheory.NewAPIClient(configuration)
  contextWithAPIKey := context.WithValue(context.Background(), basistheory.ContextAPIKeys, map[string]basistheory.APIKey{
    "ApiKey": {Key: "key_N88mVGsp3sCXkykyN2EFED"},
  })

  updateTenantRequest := *basistheory.NewUpdateTenantRequest("My Example Tenant")
  updateTenantRequest.SetSettings(map[string]string{
    "deduplicate_tokens": "true",
  })

  tenant, httpResponse, err := apiClient.TenantsApi.Update(contextWithAPIKey).UpdateTenantRequest(updateTenantRequest).Execute()
}

Response

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

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

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

Permissions

tenant:update

Request Parameters

Attribute	Required	Type	Default	Description
`name`	true	string	`null`	The name of the Tenant. Has a maximum length of `200`
`settings`	false	string	Tenant Settings	The settings for the Tenant

Response

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

Delete Tenant

Request

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

import { BasisTheory } from '@basis-theory/basis-theory-js';

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

await bt.tenants.delete();

using BasisTheory.net.Tenants;

var client = new TenantClient("key_N88mVGsp3sCXkykyN2EFED");

await client.DeleteAsync();

import basistheory
from basistheory.api import tenants_api

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="key_CxEaZMmFu3UAcuNcCbvBVu")) as api_client:
    tenants_client = tenants_api.TenantsApi(api_client)

    tenants_client.delete()

package main

import (
  "context"
  "github.com/Basis-Theory/basistheory-go/v3"
)

func main() {
  configuration := basistheory.NewConfiguration()
  apiClient := basistheory.NewAPIClient(configuration)
  contextWithAPIKey := context.WithValue(context.Background(), basistheory.ContextAPIKeys, map[string]basistheory.APIKey{
    "ApiKey": {Key: "key_N88mVGsp3sCXkykyN2EFED"},
  })

  httpResponse, err := apiClient.TenantsApi.Delete(contextWithAPIKey).Execute()
}

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

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

Permissions

tenant:delete

Response

Returns an error if the Tenant failed to delete.

Get Tenant Usage Report

Request

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

import { BasisTheory } from '@basis-theory/basis-theory-js';

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

const tenantUsageReport = await bt.tenants.retrieveUsageReport();

using BasisTheory.net.Tenants;

var client = new TenantClient("key_N88mVGsp3sCXkykyN2EFED");

var tenantUsageReport = await client.GetTenantUsageReportAsync();

import basistheory
from basistheory.api import tenants_api

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="key_N88mVGsp3sCXkykyN2EFED")) as api_client:
    tenants_client = tenants_api.TenantsApi(api_client)

    tenant_usage_report = tenants_client.get_tenant_usage_report()

package main

import (
  "context"
  "github.com/Basis-Theory/basistheory-go/v3"
)

func main() {
  configuration := basistheory.NewConfiguration()
  apiClient := basistheory.NewAPIClient(configuration)
  contextWithAPIKey := context.WithValue(context.Background(), basistheory.ContextAPIKeys, map[string]basistheory.APIKey{
    "ApiKey": {Key: "key_N88mVGsp3sCXkykyN2EFED"},
  })

  tenantUsageReport, httpResponse, err := apiClient.TenantsApi.GetTenantUsageReport(contextWithAPIKey).Execute()
}

Response

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

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

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

Permissions

report:read

Response

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

Tenant Members

Tenant Members enable user management operations within the context of a Tenant. New members can be invited via e-mail to join an existing tenant. Upon accepting a Tenant Invitation, a new Tenant Member will be created.

Tenant Member Object

Attribute	Type	Description
`id`	uuid	Unique identifier of the Tenant Member
`tenant_id`	uuid	The Tenant ID that the membership is attached
`role`	string	The Role assigned to the Tenant Member
`user`	user object	The User which this membership is attached to
`created_by`	uuid	(Optional) The ID of the User or Application that created the Tenant Member
`created_at`	date	(Optional) Created date of the Tenant Member in ISO 8601 format
`modified_by`	uuid	(Optional) The ID of the User or Application that last modified the Tenant Member
`modified_at`	date	(Optional) Last modified date of the Tenant Member in ISO 8601 format

Roles

Role	Description
`OWNER`	The `OWNER` role is automatically assigned to the Tenant Owner and grants full access to all features. The Tenant `OWNER` cannot be deleted.
`ADMIN`	The `ADMIN` role is assigned by default to all members and grants full access to all features.

User Object

Attribute	Type	Description
`id`	uuid	Unique identifier of the User
`email`	string	(Optional) The e-mail address of the User
`first_name`	string	(Optional) The User's first name
`last_name`	string	(Optional) The User's last name
`picture`	string	(Optional) A URI pointing to the User's picture

Tenant Invitation Object

Attribute	Type	Description
`id`	uuid	Unique identifier of the Tenant Invitation
`tenant_id`	uuid	The Tenant ID that the invitation is tied to. When the invitation is accepted, a new Tenant Member will be created in this Tenant.
`email`	string	The invitee's e-mail address
`status`	string	The status of the invitation (i.e. `PENDING` or `EXPIRED`)
`expires_at`	date	The expiration date of the invitation is ISO 8601 format. By default, the invitation expires 72 hours from the time it was created. Invitations can be resent to extend the expiration, but doing so will invalidate the previous invitation link sent to the invitee.
`created_by`	uuid	(Optional) The ID of the User or Application that created the Tenant Invitation
`created_at`	date	(Optional) Created date of the Tenant Invitation in ISO 8601 format
`modified_by`	uuid	(Optional) The ID of the User or Application that last modified the Tenant Invitation
`modified_at`	date	(Optional) Last modified date of the Tenant Invitation in ISO 8601 format

List Tenant Members

Request

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

import { BasisTheory } from '@basis-theory/basis-theory-js';

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

const tenantMembers = await bt.tenants.listMembers();

using BasisTheory.net.Tenants;

var client = new TenantClient("key_N88mVGsp3sCXkykyN2EFED");

var tenantMembers = await client.GetMembersAsync();

import basistheory
from basistheory.api import tenants_api

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="key_N88mVGsp3sCXkykyN2EFED")) as api_client:
    tenant_client = tenants_api.TenantsApi(api_client)

    tenant_members = tenant_client.get_members()

package main

import (
  "context"
  "github.com/Basis-Theory/basistheory-go/v3"
)

func main() {
  configuration := basistheory.NewConfiguration()
  apiClient := basistheory.NewAPIClient(configuration)
  contextWithAPIKey := context.WithValue(context.Background(), basistheory.ContextAPIKeys, map[string]basistheory.APIKey{
    "ApiKey": {Key: "key_N88mVGsp3sCXkykyN2EFED"},
  })

  tenantMembers, httpResponse, err := apiClient.TenantsApi.GetMembers(contextWithAPIKey).Execute()
}

Response

{
  "pagination": {...},
  "data": [
    {
      "id": "5540a02f-99e7-46de-8f41-1b3cf7b2a3d2",
      "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
      "role": "ADMIN",
      "user": {
        "id": "dc5fca8c-dd54-41df-98fc-50d7a1e7fb4d",
        "email": "[email protected]",
        "first_name": "Jane",
        "last_name": "Doe",
        "picture": ""
      },
      "created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
      "created_at": "2020-09-15T15:53:00+00:00",
      "modified_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
      "modified_at": "2021-03-01T08:23:14+00:00"
    },
    {...},
    {...}
  ]
}

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

Get a list of Tenant Members for the Tenant.

Permissions

tenant:member:read

Query Parameters

Parameter	Required	Type	Default	Description
`user_id`	false	uuid	`null`	One to many User IDs to query for. Multiple IDs can be passed in the form `?user_id=<value1>&user_id=<value2>`.
`page`	false	integer	`1`	Page number of the results to return.
`size`	false	integer	`20`	Number of the results to return per page. Maximum size of 50 results.

Response

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

Delete Tenant Member

Request

curl "https://api.basistheory.com/tenants/self/members/5540a02f-99e7-46de-8f41-1b3cf7b2a3d2" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED" \
  -X "DELETE"

import { BasisTheory } from '@basis-theory/basis-theory-js';

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

await bt.tenants.deleteMember('5540a02f-99e7-46de-8f41-1b3cf7b2a3d2');

using BasisTheory.net.Tenants;

var client = new TenantClient("key_N88mVGsp3sCXkykyN2EFED");

await client.DeleteMemberAsync("5540a02f-99e7-46de-8f41-1b3cf7b2a3d2");

import basistheory
from basistheory.api import tenants_api

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="key_N88mVGsp3sCXkykyN2EFED")) as api_client:
    tenant_client = tenants_api.TenantsApi(api_client)

    tenant_client.delete_member(member_id="5540a02f-99e7-46de-8f41-1b3cf7b2a3d2")

package main

import (
  "context"
  "github.com/Basis-Theory/basistheory-go/v3"
)

func main() {
  configuration := basistheory.NewConfiguration()
  apiClient := basistheory.NewAPIClient(configuration)
  contextWithAPIKey := context.WithValue(context.Background(), basistheory.ContextAPIKeys, map[string]basistheory.APIKey{
    "ApiKey": {Key: "key_N88mVGsp3sCXkykyN2EFED"},
  })

  httpResponse, err := apiClient.TenantsApi.DeleteMember(contextWithAPIKey, "5540a02f-99e7-46de-8f41-1b3cf7b2a3d2").Execute()
}

DELETE https://api.basistheory.com/tenants/self/members/{id}

Delete a Tenant Member by ID from the Tenant. Deleting a Tenant Member will revoke all access from the Tenant.

Permissions

tenant:member:delete

URI Parameters

Parameter	Required	Type	Default	Description
`id`	true	uuid	`null`	The ID of the Tenant Member

Response

Returns an error if the Tenant Member could not be deleted.

Create Tenant Invitation

Request

curl "https://api.basistheory.com/tenants/self/invitations" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED" \
  -H "Content-Type: application/json" \
  -X "POST" \
  -d '{
    "email": "[email protected]",
  }'

import { BasisTheory } from '@basis-theory/basis-theory-js';

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

const createdInvitation = await bt.tenants.createInvitations({
  email: '[email protected]',
});

using BasisTheory.net.Tenants;

var client = new TenantClient("key_N88mVGsp3sCXkykyN2EFED");

var createdInvitation = await client.CreateInvitationAsync(new TenantInvitation
{
    Email = "[email protected]"
});

import basistheory
from basistheory.api import tenants_api
from basistheory.model.create_tenant_invitation_request import CreateTenantInvitationRequest

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="key_N88mVGsp3sCXkykyN2EFED")) as api_client:
    tenant_client = tenants_api.TenantsApi(api_client)

    created_invitation = tenant_client.create_invitation(create_tenant_invitation_request=CreateTenantInvitationRequest(
        email="[email protected]"
    ))

package main

import (
  "context"
  "github.com/Basis-Theory/basistheory-go/v3"
)

func main() {
  configuration := basistheory.NewConfiguration()
  apiClient := basistheory.NewAPIClient(configuration)
  contextWithAPIKey := context.WithValue(context.Background(), basistheory.ContextAPIKeys, map[string]basistheory.APIKey{
    "ApiKey": {Key: "key_N88mVGsp3sCXkykyN2EFED"},
  })

  createTenantInvitationRequest := *basistheory.NewCreateTenantInvitationRequest("[email protected]")

  createdInvitation, httpResponse, err := apiClient.TenantsApi.CreateInvitation(contextWithAPIKey).CreateTenantInvitationRequest(createTenantInvitationRequest).Execute()
}

Response

{
  "id": "fb32ea26-2185-4ad2-a7bf-2fe69c00ae13",
  "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
  "email": "[email protected]",
  "status": "PENDING",
  "expires_at": "2020-09-18T15:53:00+00:00",
  "created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
  "created_at": "2020-09-15T15:53:00+00:00"
}

POST https://api.basistheory.com/tenants/self/invitations

Invite a new member to join this Tenant. Creating a Tenant Invitation will send an e-mail to the recipient containing a link to accept the invitation.

Permissions

tenant:invitation:create

Request Parameters

Attribute	Required	Type	Default	Description
`email`	true	string	`null`	The invitee's e-mail address. Has to be a well-formed e-mail address (RFC 5322).

Response

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

Resend Tenant Invitation

Request

curl "https://api.basistheory.com/tenants/self/invitations/fb32ea26-2185-4ad2-a7bf-2fe69c00ae13/resend" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED" \
  -H "Content-Type: application/json" \
  -X "POST"

import { BasisTheory } from '@basis-theory/basis-theory-js';

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

const resentInvitation = await bt.tenants.resendInvitation('fb32ea26-2185-4ad2-a7bf-2fe69c00ae13');

using BasisTheory.net.Tenants;

var client = new TenantClient("key_N88mVGsp3sCXkykyN2EFED");

var resentInvitation = await client.ResendInvitationAsync("fb32ea26-2185-4ad2-a7bf-2fe69c00ae13");

import basistheory
from basistheory.api import tenants_api

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="key_N88mVGsp3sCXkykyN2EFED")) as api_client:
    tenant_client = tenants_api.TenantsApi(api_client)

    resent_invitation = tenant_client.resend_invitation(invitation_id="dfd0319e-e978-4d2a-9109-f8a9048088bd")

package main

import (
  "context"
  "github.com/Basis-Theory/basistheory-go/v3"
)

func main() {
  configuration := basistheory.NewConfiguration()
  apiClient := basistheory.NewAPIClient(configuration)
  contextWithAPIKey := context.WithValue(context.Background(), basistheory.ContextAPIKeys, map[string]basistheory.APIKey{
    "ApiKey": {Key: "key_N88mVGsp3sCXkykyN2EFED"},
  })

  resentInvitation, httpResponse, err := apiClient.TenantsApi.ResendInvitation(contextWithAPIKey, "dfd0319e-e978-4d2a-9109-f8a9048088bd").Execute()
}

Response

{
  "id": "fb32ea26-2185-4ad2-a7bf-2fe69c00ae13",
  "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
  "email": "[email protected]",
  "status": "PENDING",
  "expires_at": "2020-09-18T15:53:00+00:00",
  "created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
  "created_at": "2020-09-15T15:53:00+00:00"
}

POST https://api.basistheory.com/tenants/self/invitations/{id}/resend

Resend a pending or expired Tenant Invitation. Resending the invitation will extend the expiration by 72 hours and invalidate any previous invitation link(s) sent to the recipient.

Permissions

tenant:invitation:create tenant:invitation:update

Response

Returns a Tenant Invitation if the Tenant Invitation was resent. Returns an error if there were validation errors, or the Tenant Invitation failed to resend.

List Tenant Invitations

Request

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

import { BasisTheory } from '@basis-theory/basis-theory-js';

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

const invitations = await bt.tenants.listInvitations();

using BasisTheory.net.Tenants;

var client = new TenantClient("key_N88mVGsp3sCXkykyN2EFED");

var invitations = await client.GetInvitationsAsync();

import basistheory
from basistheory.api import tenants_api

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="key_N88mVGsp3sCXkykyN2EFED")) as api_client:
    tenant_client = tenants_api.TenantsApi(api_client)

    invitations = tenant_client.get_invitations()

package main

import (
  "context"
  "github.com/Basis-Theory/basistheory-go/v3"
)

func main() {
  configuration := basistheory.NewConfiguration()
  apiClient := basistheory.NewAPIClient(configuration)
  contextWithAPIKey := context.WithValue(context.Background(), basistheory.ContextAPIKeys, map[string]basistheory.APIKey{
    "ApiKey": {Key: "key_N88mVGsp3sCXkykyN2EFED"},
  })

  invitations, httpResponse, err := apiClient.TenantsApi.GetInvitations(contextWithAPIKey).Execute()
}

Response

{
  "pagination": {...},
  "data": [
    {
      "id": "fb32ea26-2185-4ad2-a7bf-2fe69c00ae13",
      "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
      "email": "[email protected]",
      "status": "PENDING",
      "expires_at": "2020-09-18T15:53:00+00:00",
      "created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
      "created_at": "2020-09-15T15:53:00+00:00"
    },
    {...},
    {...}
  ]
}

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

Get a list of Tenant Invitations for the Tenant.

Permissions

tenant:invitation:read

Query Parameters

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

Response

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

Get a Tenant Invitation

Request

curl "https://api.basistheory.com/tenants/self/invitations/fb32ea26-2185-4ad2-a7bf-2fe69c00ae13" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED"

import { BasisTheory } from '@basis-theory/basis-theory-js';

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

const invitation = await bt.tenants.retrieveInvitation('fb32ea26-2185-4ad2-a7bf-2fe69c00ae13');

using BasisTheory.net.Tenants;

var client = new TenantClient("key_N88mVGsp3sCXkykyN2EFED");

var invitation = await client.GetInvitationByIdAsync("fb32ea26-2185-4ad2-a7bf-2fe69c00ae13");

import basistheory
from basistheory.api import tenants_api

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="key_N88mVGsp3sCXkykyN2EFED")) as api_client:
    tenant_client = tenants_api.TenantsApi(api_client)

    invitation = tenant_client.get_invitation_by_id(invitation_id="fb32ea26-2185-4ad2-a7bf-2fe69c00ae13")

Response

{
  "id": "fb32ea26-2185-4ad2-a7bf-2fe69c00ae13",
  "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
  "email": "[email protected]",
  "status": "PENDING",
  "expires_at": "2020-09-18T15:53:00+00:00",
  "created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
  "created_at": "2020-09-15T15:53:00+00:00"
}

GET https://api.basistheory.com/tenants/self/invitations/{id}

Get a Tenant Invitation by ID in the Tenant.

Permissions

tenant:invitation:read

URI Parameters

Parameter	Required	Type	Default	Description
`id`	true	uuid	`null`	The ID of the Tenant Invitation

Response

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

Delete Tenant Invitation

Request

curl "https://api.basistheory.com/tenants/self/invitations/fb32ea26-2185-4ad2-a7bf-2fe69c00ae13" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED" \
  -X "DELETE"

import { BasisTheory } from '@basis-theory/basis-theory-js';

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

await bt.tenants.deleteInvitation('fb32ea26-2185-4ad2-a7bf-2fe69c00ae13');

using BasisTheory.net.Tenants;

var client = new TenantClient("key_N88mVGsp3sCXkykyN2EFED");

await client.DeleteInvitationAsync("fb32ea26-2185-4ad2-a7bf-2fe69c00ae13");

import basistheory
from basistheory.api import tenants_api

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="key_N88mVGsp3sCXkykyN2EFED")) as api_client:
    tenant_client = tenants_api.TenantsApi(api_client)

    tenant_client.delete_invitation(invitation_id="fb32ea26-2185-4ad2-a7bf-2fe69c00ae13")

package main

import (
  "context"
  "github.com/Basis-Theory/basistheory-go/v3"
)

func main() {
  configuration := basistheory.NewConfiguration()
  apiClient := basistheory.NewAPIClient(configuration)
  contextWithAPIKey := context.WithValue(context.Background(), basistheory.ContextAPIKeys, map[string]basistheory.APIKey{
    "ApiKey": {Key: "key_N88mVGsp3sCXkykyN2EFED"},
  })

  httpResponse, err := apiClient.TenantsApi.DeleteInvitation(contextWithAPIKey, "fb32ea26-2185-4ad2-a7bf-2fe69c00ae13").Execute()
}

DELETE https://api.basistheory.com/tenants/self/invitations/{id}

Delete a Tenant Invitation by ID from the Tenant. Deleting a Tenant Invitation will invalidate any outstanding invitation links sent to the recipient.

Permissions

tenant:invitation:delete

URI Parameters

Parameter	Required	Type	Default	Description
`id`	true	uuid	`null`	The ID of the Tenant Invitation

Response

Returns an error if the Tenant Invitation could not be deleted.

Token Types

Basis Theory offers several pre-configured token types for various use-cases and compliance requirements. Token Types define the rules around a data type such as validation requirements, default token containers, fingerprint expressions, and mask expressions.

Token
Card
Bank
Card Number
US Bank Account Number
US Bank Routing Number
Social Security Number
Employer ID Number

Token

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

Token Attribute	Value
Type	`token`
Default Containers	`[ "/general/high/" ]`
Input Validation	None
Input Length	Any
Default Fingerprint Expression	`{{ data \| stringify}}`
Default Mask Expression	`null`

Card

Token Attribute	Value
Type	`card`
Default Containers	`[ "/pci/high/" ]`
Input Validation	See Card Object for validation requirements
Default Fingerprint Expression	`{{ data.number }}`
Default Mask Expression	`{ "number": "{{ data.number \| reveal_last: 4 }}", "expiration_month": "{{ data.expiration_month }}", "expiration_year": "{{ data.expiration_year }}" }`

Bank

Token Attribute	Value
Type	`bank`
Default Containers	`[ "/bank/high/" ]`
Input Validation	See Bank Object for validation requirements
Default Fingerprint Expression	`{{ data.account_number }}\|{{ data.routing_number }}`
Default Mask Expression	`{ "routing_number": "{{ data.routing_number }}", "account_number": "{{ data.account_number \| reveal_last: 4 }}" }`

Card Number

Token Attribute	Value
Type	`card_number`
Default Containers	`[ "/pci/high/" ]`
Input Validation	Luhn-valid, numeric
Input Length	13 - 19
Default Fingerprint Expression	`{{ data }}`
Default Mask Expression	`{{ data \| reveal_last: 4 }}`

Examples:

Input Data	Masked Value
4242424242424242	XXXXXXXXXXXX4242
36227206271667	XXXXXXXXXX1667

US Bank Account Number

Token Attribute	Value
Type	`us_bank_account_number`
Default Containers	`[ "/bank/high/" ]`
Input Validation	Numeric
Input Length	3 - 17
Default Fingerprint Expression	`{{ data }}`
Default Mask Expression	`{{ data \| reveal_last: 4 }}`

Examples:

Input Data	Masked Value
1234567890	XXXXXX7890

US Bank Routing Number

Token Attribute	Value
Type	`us_bank_routing_number`
Default Containers	`[ "/bank/low/" ]`
Input Validation	Numeric, ABA-valid
Input Length	9
Default Fingerprint Expression	`{{ data }}`
Default Mask Expression	`{{ data \| reveal_last: 4 }}`

Token Attribute	Value
Type	`social_security_number`
Default Containers	`[ "/pii/high/" ]`
Input Validation	Numeric with optional delimiter of `"-"`
Input Length	9 (not including delimiting characters)
Default Fingerprint Expression	`{{ data \| remove: '-' }}`
Default Mask Expression	`{{ data \| reveal_last: 4 }}`

Examples:

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

Employer ID Number

Token Attribute	Value
Type	`employer_id_number`
Default Containers	`[ "/pii/high/" ]`
Input Validation	Numeric with optional delimiter of `"-"`
Input Length	9 (not including delimiting characters)
Default Fingerprint Expression	`{{ data \| remove: '-' }}`
Default Mask Expression	`{{ data \| reveal_last: 4 }}`

Examples:

Input Data	Masked Value
123456789	XXXXX6789
12-3456789	XX-XXX6789

Tokens

Token Object

Attribute	Type	Description
`id`	string	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
`mask`	any	An expression defining the mask to apply when retrieving token data with restricted permissions.
`fingerprint`	string	Uniquely identifies the contents of this token. See Token Types for the default expression for each token type.
`containers`	array	Array of containers to place this token within. Each container is a path representing a logical grouping of tokens. See Token Containers for details.
`metadata`	map	A key-value map of strings containing non-sensitive data.
`created_by`	uuid	The Application ID which created the token
`created_at`	date	Created date of the token in ISO 8601 format
`modified_by`	uuid	(Optional) The Application ID which last modified the token
`modified_at`	date	(Optional) Last modified date of the token in ISO 8601 format
`search_indexes`	array	(Optional) Array of search index expressions used when creating the token.
`fingerprint_expression`	string	(Optional) An expression defining the value to fingerprint when creating the token.
`expires_at`	string	(Optional) The token expiration date.

Token Data Validations

Bank Object

Attribute	Required	Type	Default	Description
`routing_number`	true	string	`null`	Nine-digit ABA routing number. Its checksum is validated.
`account_number`	true	string	`null`	Account number up to seventeen-digits

Card Object

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

Test Card Numbers

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

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

Token Expiration

By default a created token will not expire, however, users can optionally set the expires_at property with an ISO8601 DateTime when creating a token to determine its expiration date. An expired token is deleted from the tenant up to 1 hour after it's expiration time.

Expiration Date Formats

Format	Example
`DateTime` String w/ Offset	8/26/2030 7:23:57 PM -07:00
`ShortDate` String	9/27/2030

Create Token

Request

curl "https://api.basistheory.com/tokens" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED" \
  -H "Content-Type: application/json" \
  -X "POST" \
  -d '{
    "type": "token",
    "data": "Sensitive Value",
    "mask": "{{ data | reveal_last: 4 }}",
    "containers": [ "/general/high/" ],
    "metadata": {
      "nonSensitiveField": "Non-Sensitive Value"
    },
    "search_indexes": [
      "{{ data }}",
      "{{ data | last4 }}"
    ],
    "fingerprint_expression": "{{ data }}",
    "deduplicate_token": true,
    "expires_at": "8/26/2030 7:23:57 PM -07:00"
  }'

import { BasisTheory } from '@basis-theory/basis-theory-js';

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

const token = await bt.tokens.create({
  type: 'token',
  data: 'Sensitive Value',
  mask: '{{ data | reveal_last: 4 }}',
  containers: ['/general/high/'],
  metadata: {
    nonSensitiveField: 'Non-Sensitive Value'
  },
  searchIndexes: [
    '{{ data }}',
    '{{ data | last4 }}'
  ],
  fingerprintExpression: '{{ data }}',
  deduplicateToken: true,
  expiresAt: '8/26/2030 7:23:57 PM -07:00'
});

using BasisTheory.net.Tokens;

var client = new TokenClient("key_N88mVGsp3sCXkykyN2EFED");

var token = await client.CreateAsync(new Token {
  Type = "token",
  Data = "Sensitive Value",
  Mask = "{{ data | reveal_last: 4 }}",
  Containers = new List<string> { "/general/high/" },
  Metadata = new Dictionary<string, string> {
    { "nonSensitiveField",  "Non-Sensitive Value" }
  },
  SearchIndexes = new List<string> {
    "{{ data }}",
    "{{ data | last4 }}"
  }
  FingerprintExpression = "{{ data }}",
  DeduplicateToken = true,
  ExpiresAt = "8/26/2030 7:23:57 PM -07:00"
});

import basistheory
from basistheory.api import tokens_api
from basistheory.model.create_token_request import CreateTokenRequest

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

    token = token_client.create(create_token_request=CreateTokenRequest(
        type="token",
        data="Sensitive Value",
        mask="{{ data | reveal_last: 4 }}",
        metadata={
            "nonSensitiveField": "Non-Sensitive Value"
        },
        containers=["/general/high/"],
        search_indexes=[
          "{{ data }}",
          "{{ data | last4 }}"
        ],
        fingerprint_expression="{{ data }}",
        expires_at="8/26/2030 7:23:57 PM -07:00"
    ))

package main

import (
  "context"
  "github.com/Basis-Theory/basistheory-go/v3"
)

func main() {
  configuration := basistheory.NewConfiguration()
  apiClient := basistheory.NewAPIClient(configuration)
  contextWithAPIKey := context.WithValue(context.Background(), basistheory.ContextAPIKeys, map[string]basistheory.APIKey{
    "ApiKey": {Key: "key_N88mVGsp3sCXkykyN2EFED"},
  })

  createTokenRequest := *basistheory.NewCreateTokenRequest("Sensitive Value")
  createTokenRequest.SetMask("{{ data | reveal_last: 4 }}")
  createTokenRequest.SetType("token")
  createTokenRequest.SetMetadata(map[string]string{
    "myMetadata": "myMetadataValue",
  })
  createTokenRequest.SetSearchIndexes([]string{"{{ data }}", "{{ data | last4 }}"})
  createTokenRequest.SetFingerprintExpression("{{ data }}")
  createTokenRequest.SetDeduplicateToken(true)
  createTokenRequest.SetContainers([]string{"/general/high/"})
  createTokenRequest.SetExpiresAt("8/26/2030 7:23:57 PM -07:00")

  createTokenResponse, createTokenHttpResponse, createErr := apiClient.TokensApi.Create(contextWithAPIKey).CreateTokenRequest(createTokenRequest).Execute()
}

Response

{
  "id": "c06d0789-0a38-40be-b7cc-c28a718f76f1",
  "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
  "type": "token",
  "data": "XXXXXXXXXXXalue",
  "mask": "{{ data | reveal_last: 4 }}",
  "containers": ["/general/high/"],
  "metadata": {
    "nonSensitiveField": "Non-Sensitive Value"
  },
  "search_indexes": [
    "{{ data }}",
    "{{ data | last4 }}"
  ],
  "fingerprint_expression": "{{ data }}",
  "created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
  "created_at": "2020-09-15T15:53:00+00:00",
  "expires_at": "2030-08-26T19:23:57-07:00"
}

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

Create a new token for the Tenant.

Permissions

token:create

Request Parameters

Attribute	Required	Type	Default	Description
`id`	false	string	`null`	A value or expression specifying the token's ID. If not specified, a UUID will be assigned.
`type`	true	string	`null`	Token type of the token
`data`	true	any	`null`	Token data. Can be an object, array, or any primitive type such as an integer, boolean, or string
`mask`	false	any	Depends on the token type	Token data mask. Can be an object, array, or any primitive type such as an integer, boolean, or string. See mask expressions.
`containers`	false	array	Depends on the token type	Array of containers to place this token within. Each container is a path representing a logical grouping of tokens. See Token Containers for details.
`metadata`	false	map	`null`	A key-value map of strings containing non-sensitive data.
`search_indexes`	false	array	`null`	Array of expressions used to generate indexes to be able to search against.
`fingerprint_expression`	false	string	`{{ data \| stringify }}`	Expressions used to fingerprint your token.
`deduplicate_token`	false	bool	`null`	Whether the token is deduplicated on creation.
`expires_at`	false	string	`null`	ISO8601 compatible Token expiration DateTime. See Token Expiration for more details.

Response

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

List Tokens

Request

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

import { BasisTheory } from '@basis-theory/basis-theory-js';

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

const tokens = await bt.tokens.list();

using BasisTheory.net.Tokens;

var client = new TokenClient("key_N88mVGsp3sCXkykyN2EFED");

var tokens = await client.GetAsync();

import basistheory
from basistheory.api import tokens_api

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

    tokens = token_client.get()

package main

import (
  "context"
  "github.com/Basis-Theory/basistheory-go/v3"
)

func main() {
  configuration := basistheory.NewConfiguration()
  apiClient := basistheory.NewAPIClient(configuration)
  contextWithAPIKey := context.WithValue(context.Background(), basistheory.ContextAPIKeys, map[string]basistheory.APIKey{
    "ApiKey": {Key: "key_N88mVGsp3sCXkykyN2EFED"},
  })

  tokens, httpResponse, err := apiClient.TokensApi.Get(contextWithAPIKey).Execute()
}

Response

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

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

Get a list of tokens for the Tenant, supporting basic search criteria. If you need to perform a more advanced token search, see Search Tokens.

Permissions

token:read

Query Parameters

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

Response

Returns a paginated object with the data property containing an array of tokens. Token data will be returned according to the transform applied within the requesting Application's Access Controls. 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 "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED"

import { BasisTheory } from '@basis-theory/basis-theory-js';

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

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

using BasisTheory.net.Tokens;

var client = new TokenClient("key_N88mVGsp3sCXkykyN2EFED");

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

import basistheory
from basistheory.api import tokens_api

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

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

package main

import (
  "context"
  "github.com/Basis-Theory/basistheory-go/v3"
)

func main() {
  configuration := basistheory.NewConfiguration()
  apiClient := basistheory.NewAPIClient(configuration)
  contextWithAPIKey := context.WithValue(context.Background(), basistheory.ContextAPIKeys, map[string]basistheory.APIKey{
    "ApiKey": {Key: "key_N88mVGsp3sCXkykyN2EFED"},
  })

  token, httpResponse, err := apiClient.TokensApi.GetById(contextWithAPIKey, "c06d0789-0a38-40be-b7cc-c28a718f76f1").Execute()
}

Response

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

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

Get a token by ID in the Tenant.

Permissions

token:read

URI Parameters

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

Response

Returns a token with the id provided. Token data will be returned according to the transform applied within the requesting Application's Access Controls. Returns an error if the token could not be retrieved.

Update Token

Request

curl "https://api.basistheory.com/tokens/c06d0789-0a38-40be-b7cc-c28a718f76f1" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED" \
  -H "Content-Type: application/merge-patch+json" \
  -X "PATCH" \
  -d '{
    "data": "Sensitive Value",
    "mask": "{{ data | reveal_last: 4 }}",
    "metadata": {
      "nonSensitiveField": "Non-Sensitive Value"
    },
    "search_indexes": [
      "{{ data }}",
      "{{ data | last4 }}"
    ],
    "fingerprint_expression": "{{ data }}",
    "deduplicate_token": true,
  }'

import { BasisTheory } from '@basis-theory/basis-theory-js';

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

const token = await bt.tokens.update('c06d0789-0a38-40be-b7cc-c28a718f76f1', {
  data: 'Sensitive Value',
  mask: '{{ data | reveal_last: 4 }}',
  metadata: {
    nonSensitiveField: 'Non-Sensitive Value'
  },
  searchIndexes: [
    '{{ data }}',
    '{{ data | last4 }}'
  ],
  fingerprintExpression: "{{ data }}",
  deduplicateToken: true,
});

using BasisTheory.net.Tokens;

var client = new TokenClient("key_N88mVGsp3sCXkykyN2EFED");

var token = await client.UpdateAsync("c06d0789-0a38-40be-b7cc-c28a718f76f1", new TokenUpdateRequest {
  Data = "Sensitive Value",
  Mask = "{{ data | reveal_last: 4 }}",
  Metadata = new Dictionary<string, string> {
    { "nonSensitiveField",  "Non-Sensitive Value" }
  },
  SearchIndexes = new List<string> {
    "{{ data }}",
    "{{ data | last4 }}"
  }
  FingerprintExpression = "{{ data }}",
  DeduplicateToken = true,
});

import basistheory
from basistheory.api import tokens_api
from basistheory.model.update_token_request import UpdateTokenRequest

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

    token = token_client.update(id="c06d0789-0a38-40be-b7cc-c28a718f76f1", update_token_request=UpdateTokenRequest(
        data="Sensitive Value",
        mask="{{ data | reveal_last: 4 }}",
        metadata={
            "nonSensitiveField": "Non-Sensitive Value"
        },
        search_indexes=[
          "{{ data }}",
          "{{ data | last4 }}"
        ],
        fingerprint_expression="{{ data }}"
    ))

package main

import (
  "context"
  "github.com/Basis-Theory/basistheory-go/v3"
)

func main() {
  configuration := basistheory.NewConfiguration()
  apiClient := basistheory.NewAPIClient(configuration)
  contextWithAPIKey := context.WithValue(context.Background(), basistheory.ContextAPIKeys, map[string]basistheory.APIKey{
    "ApiKey": {Key: "key_N88mVGsp3sCXkykyN2EFED"},
  })

  updateTokenRequest := *basistheory.NewUpdateTokenRequest("Sensitive Value")
  updateTokenRequest.SetMask("{{ data | reveal_last: 4 }}")
  updateTokenRequest.SetMetadata(map[string]string{
    "myMetadata": "myMetadataValue",
  })
  updateTokenRequest.SetSearchIndexes([]string{"{{ data }}", "{{ data | last4 }}"})
  updateTokenRequest.SetFingerprintExpression("{{ data }}")

  updateTokenResponse, updateTokenHttpResponse, createErr := apiClient.TokensApi.Update(contextWithAPIKey, "c06d0789-0a38-40be-b7cc-c28a718f76f1").UpdateTokenRequest(updateTokenRequest).Execute()
}

Response

{
  "id": "c06d0789-0a38-40be-b7cc-c28a718f76f1",
  "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
  "type": "token",
  "data": "XXXXXXXXXXXalue",
  "mask": "{{ data | reveal_last: 4 }}",
  "containers": ["/general/high/"],
  "metadata": {
    "nonSensitiveField": "Non-Sensitive Value"
  },
  "search_indexes": [
    "{{ data }}",
    "{{ data | last4 }}"
  ],
  "fingerprint_expression": "{{ data }}",
  "created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
  "created_at": "2020-09-15T15:53:00+00:00"
}

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

Update an existing token for the Tenant.

Permissions

token:update

Request Parameters

Attribute	Required	Type	Behavior	Description
`data`	false	any	Merge Patch (see RFC 7386)	Token data. Can be an object, array, or any primitive type such as an integer, boolean, or string
`mask`	false	any	Merge Patch (see RFC 7386)	Token data mask. Can be an object, array, or any primitive type such as an integer, boolean, or string. See mask expressions.
`metadata`	false	map	Merge Patch (see RFC 7386)	A key-value map of strings containing non-sensitive data.
`containers`	false	array	Replace	Array of containers to place this token within. Each container is a path representing a logical grouping of tokens. See Token Containers for details.
`search_indexes`	false	array	Replace	Array of expressions used to generate indexes to be able to search against.
`fingerprint_expression`	false	string	Replace	Expressions used to fingerprint your token.
`deduplicate_token`	false	bool	Replace	Whether the token is deduplicated on creation.

Response

Returns the updated token if successful. Returns an error if there were validation errors, or the token failed to create.

Search Tokens

Request

curl "https://api.basistheory.com/tokens/search" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED" \
  -H "Content-Type: application/json" \
  -X "POST" \
  -d '{
    "query": "data:6789 AND type:social_security_number",
    "page": 1,
    "size": 20
  }'

import { BasisTheory } from '@basis-theory/basis-theory-js';

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

const tokens = await bt.tokens.search({
  query: 'data:6789 AND type:social_security_number',
  page: 1,
  size: 20
});

using BasisTheory.net.Tokens;

var client = new TokenClient("key_N88mVGsp3sCXkykyN2EFED");

var tokens = await client.SearchAsync(new TokenSearchRequest {
  Query = "data:6789 AND type:social_security_number",
  Page = 1,
  Size = 20);

import basistheory
from basistheory.api import tokens_api
from basistheory.model.search_tokens_request import SearchTokensRequest

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

    tokens = token_client.search(search_tokens_request=SearchTokensRequest(
        query="data:6789 AND type:social_security_number",
        page=1,
        size=20
    ))

package main

import (
  "context"
  "github.com/Basis-Theory/basistheory-go/v3"
)

func main() {
  configuration := basistheory.NewConfiguration()
  apiClient := basistheory.NewAPIClient(configuration)
  contextWithAPIKey := context.WithValue(context.Background(), basistheory.ContextAPIKeys, map[string]basistheory.APIKey{
    "ApiKey": {Key: "key_N88mVGsp3sCXkykyN2EFED"},
  })

  searchTokenRequest := *basistheory.NewSearchTokensRequest()
  searchTokenRequest.SetQuery("data:6789 AND type:social_security_number")
  searchTokenRequest.SetPage(1)
  searchTokenRequest.SetSize(20)

  tokens, httpResponse, err := apiClient.TokensApi.Search(contextWithAPIKey).SearchTokensRequest(searchTokenRequest).Execute()
}

Response

{
  "pagination": {...},
  "data": [
    {
      "id": "c06d0789-0a38-40be-b7cc-c28a718f76f1",
      "type": "social_security_number",
      "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
      "data": "XXX-XX-6789",
      "fingerprint": "AKCUXS83DokKo4pDRKSAy4d42t9i8dcP1X2jijwEBCQH",
      "containers": ["/pii/high/"],
      "metadata": {
        "nonSensitiveField": "Non-Sensitive Value"
      },
      "search_indexes": [
        "{{ data }}",
        "{{ data | replace: '-' }}",
        "{{ data | last4 }}"
      ],
      "fingerprint_expression": "{{ data }}",
      "created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
      "created_at": "2021-03-01T08:23:14+00:00"
    },
    {...},
    {...}
  ]
}

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

Search for tokens using a Lucene-based query syntax. Use this endpoint to perform an advanced token search using token data or to build complex searches combining multiple terms with boolean operators. For simpler search use cases, see List Tokens.

Permissions

token:search

Token data will be returned in search results according to the transform applied within the requesting Application's Access Controls.

Request Parameters

Attribute	Required	Type	Default	Description
`query`	false	string	`null`	A query string using Lucene query syntax.
`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

Returns a paginated object with the data property containing an array of tokens. Token data will be returned according to the transform applied to the requesting Application's Access Controls. Returns an error if tokens could not be retrieved or when an invalid query is submitted.

Query Syntax

Token search supports a Lucene-based query syntax to build complex search criteria. A query string is comprised of one or more Terms that can be combined with the AND and OR Operators.

Search terms are formed by combining a field name and a value to search with a : - field:value. See the Searchable Token Fields table below for a complete list of supported fields. For example, to search for tokens having a type of card_number, query for: type:card_number

Token data may be searched on some token types, by performing a case-insensitive exact match to one of several indexed data patterns. As an example, the following query will search for tokens containing the data 123-45-6789: data:123-45-6789

For more detailed information about supported data searches, see Searching Data.

Phrases or values containing spaces may be searched by wrapping the searched value in quotes, for example: data:"data containing multiple words"

Metadata search terms require both a key and value to be specified in the form of metadata.key:value. Metadata will be searched for a case-insensitive, exact match. For example, to search for tokens having the metadata { customer_id: "123456" }, query for: metadata.customer_id:123456

Container search terms support both exact and wildcard matches. An exact container search will only return tokens in the searched container and will not include tokens in parent or child containers. For example, to return only tokens in the /customer-123/pii/ container, you can query: container:"/customer-123/pii/"

Wildcard container searches can be used to match on all tokens within a container or its sub-containers. The wildcard character * can only appear at the end of a container search term. For example, to return all tokens for customer-123 which may be partitioned into sub-containers /customer-123/pii/ or /customer-123/general/, you can query: container:"/customer-123/*"

Date range searches are supported using the Lucene bracketed range syntax. [START_DATE TO END_DATE] denotes an inclusive range and {START_DATE TO END_DATE} denotes an exclusive range. Values are formatted as a string in ISO 8601 format and can either represent a date or date and time in UTC. For example, to search for tokens that were created in the year 2021, you can query: created_at:[2021-01-01 TO 2021-12-31T23:59:59Z]

To search a range without a start or end date, use the wildcard * in place of the start or end date, for example: created_at:{* TO 2022-01-01}

Multiple terms may be combined using the AND, OR and NOT operators (case sensitive) and grouped using parentheses. The NOT operator could be interchanged with the ! or - symbols. For example: (type:social_security_number AND !metadata.user_id:1234) OR data:111-11-1111

Searchable Token Fields

Fields	Type	Description	Example
`id`	string	Token ID.	`id:fe24d4cc-de50-4d8c-8da7-8c7483ba21bf`
`type`	string	The token type.	`type:card_number`
`data`	string	Token data. See Searching Data for supported values.	`data:6789`
`fingerprint`	string	Token's content unique identifier.	`fingerprint:fe24d4cc-de50-4d8c-8da7-8c7483ba21bf`
`container`	string	Searches across a token's containers.	`container:"/pci/high/"`
`metadata.[key]`	string	Search against token metadata having the given `[key]`.	`metadata.user_id:34445`
`created_by`	string	Application ID which created the token.	`created_by:fe24d4cc-de50-4d8c-8da7-8c7483ba21bf`
`created_at`	date	The date or date and time a token was created in ISO 8601 format.	`created_at:[2020-01-01 TO 2020-01-28]`
`modified_by`	string	Application ID which last modified the token.	`modified_by:fe24d4cc-de50-4d8c-8da7-8c7483ba21bf`
`modified_at`	date	The last date or date and time a token was modified in ISO 8601 format.	`modified_at:[2020-01-01 TO 2020-01-28]`

Searching Data

Basis Theory currently supports data searches on social_security_number, employer_id_number and token token types. When creating tokens of these types, Basis Theory will securely index several data patterns to enable searching on these values based on the search_indexes provided in the Create Token Request or Tokenize Request.

If search_indexes are not provided when creating a token, then social_security_number and employer_id_number will have the following default search indexes:

{{ data }} which results in the input value being indexed, eg. 123-45-6789
{{ data | remove: '-'}} which results in the value without delimiters, eg. 123456789
{{ data | last4 }} which results in the last 4 digits of the value, eg. 6789

For generic tokens (type token), default indexes are not applied, and you are free to specify any desired indexes within the search_indexes property during token creation. The search_indexes property supports the use of expressions, which are based on the Liquid templating language. Each expression must result in a single value, which cannot be null or empty, otherwise a 400 error will be returned.

Any expressions contained within search_indexes will be evaluated against the token data before generating indexes. Token data searches will only return a token if there is an exact match on one of the evaluated search_indexes; full wildcard search is not currently supported.

For example, to search for a social_security_number token with the value 123-45-6789, you may search for:

data:123-45-6789 AND type:social_security_number

To search for all social_security_number tokens with the last 4 digits of 6789, you may search for:

data:6789 AND type:social_security_number

Note that the results returned by this query may not be unique if you have stored multiple social_security_number tokens ending with the same 4 digits.

Delete Token

Request

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

import { BasisTheory } from '@basis-theory/basis-theory-js';

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

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

using BasisTheory.net.Tokens;

var client = new TokenClient("key_N88mVGsp3sCXkykyN2EFED");

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

import basistheory
from basistheory.api import tokens_api

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

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

package main

import (
  "context"
  "github.com/Basis-Theory/basistheory-go/v3"
)

func main() {
  configuration := basistheory.NewConfiguration()
  apiClient := basistheory.NewAPIClient(configuration)
  contextWithAPIKey := context.WithValue(context.Background(), basistheory.ContextAPIKeys, map[string]basistheory.APIKey{
    "ApiKey": {Key: "key_N88mVGsp3sCXkykyN2EFED"},
  })

  httpResponse, err := apiClient.TokensApi.Delete(contextWithAPIKey, "c06d0789-0a38-40be-b7cc-c28a718f76f1").Execute()
}

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

Response

Returns an error if the token failed to delete.

Token Associations

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

Create Token Association

Request

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

import { BasisTheory } from '@basis-theory/basis-theory-js';

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

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

using BasisTheory.net.Tokens;

var client = new TokenClient("key_N88mVGsp3sCXkykyN2EFED");

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

import basistheory
from basistheory.api import tokens_api

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

    tokens_client.create_association("c06d0789-0a38-40be-b7cc-c28a718f76f1", "c1e565009-1984-4638-8fca-dce8a82cc2af")

package main

import (
  "context"
  "github.com/Basis-Theory/basistheory-go/v3"
)

func main() {
  configuration := basistheory.NewConfiguration()
  apiClient := basistheory.NewAPIClient(configuration)
  contextWithAPIKey := context.WithValue(context.Background(), basistheory.ContextAPIKeys, map[string]basistheory.APIKey{
    "ApiKey": {Key: "key_N88mVGsp3sCXkykyN2EFED"},
  })

  httpResponse, err := apiClient.TokensApi.CreateAssociation(contextWithAPIKey, "c06d0789-0a38-40be-b7cc-c28a718f76f1", "c1e565009-1984-4638-8fca-dce8a82cc2af").Execute()
}

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

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

Permissions

Creating an association between two existing tokens requires read permission on both the parent and child tokens.

token:read

URI Parameters

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

Response

Returns an error if the token association failed to create.

Delete Token Association

Request

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

import { BasisTheory } from '@basis-theory/basis-theory-js';

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

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

using BasisTheory.net.Tokens;

var client = new TokenClient("key_N88mVGsp3sCXkykyN2EFED");

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

import basistheory
from basistheory.api import tokens_api

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

    tokens_client.delete_association("c06d0789-0a38-40be-b7cc-c28a718f76f1", "c1e565009-1984-4638-8fca-dce8a82cc2af")

package main

import (
  "context"
  "github.com/Basis-Theory/basistheory-go/v3"
)

func main() {
  configuration := basistheory.NewConfiguration()
  apiClient := basistheory.NewAPIClient(configuration)
  contextWithAPIKey := context.WithValue(context.Background(), basistheory.ContextAPIKeys, map[string]basistheory.APIKey{
    "ApiKey": {Key: "key_N88mVGsp3sCXkykyN2EFED"},
  })

  httpResponse, err := apiClient.TokensApi.DeleteAssociation(contextWithAPIKey, "c06d0789-0a38-40be-b7cc-c28a718f76f1", "c1e565009-1984-4638-8fca-dce8a82cc2af").Execute()
}

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	string	`null`	The ID of the parent token
`child_id`	true	string	`null`	The ID of the child token

Response

Returns an error if the token association failed to delete.

Create Child Token for a Token

Request

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

import { BasisTheory } from '@basis-theory/basis-theory-js';

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

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

using BasisTheory.net.Tokens;

var client = new TokenClient("key_N88mVGsp3sCXkykyN2EFED");

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

import basistheory
from basistheory.api import tokens_api
from basistheory.model.create_token_request import CreateTokenRequest

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

    token = tokens_client.create_child("c06d0789-0a38-40be-b7cc-c28a718f76f1", create_token_request=CreateTokenRequest(
        type="token",
        data="Sensitive Value",
        metadata={
            "nonSensitiveField": "Non-Sensitive Value"
        }
    ))

package main

import (
  "context"
  "github.com/Basis-Theory/basistheory-go/v3"
)

func main() {
  configuration := basistheory.NewConfiguration()
  apiClient := basistheory.NewAPIClient(configuration)
  contextWithAPIKey := context.WithValue(context.Background(), basistheory.ContextAPIKeys, map[string]basistheory.APIKey{
    "ApiKey": {Key: "key_N88mVGsp3sCXkykyN2EFED"},
  })

  createTokenRequest := *basistheory.NewCreateTokenRequest("Sensitive Value")
  createTokenRequest.SetType("token")
  createTokenRequest.SetMetadata(map[string]string{
    "nonSensitiveField": "Non-Sensitive Value",
  })

  token, httpResposne, err := apiClient.TokensApi.CreateChild(contextWithAPIKey, "c06d0789-0a38-40be-b7cc-c28a718f76f1").CreateTokenRequest(createTokenRequest).Execute()
}

Response

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

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

Create a new child token a token in the Tenant.

Permissions

Creating a child token requires the appropriate create permission to the child token and read permission to the parent token.

token:create token:read

URI Parameters

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

Request Parameters

See Create Token for supported request parameters.

Response

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

List Child Tokens for a Token

Request

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

import { BasisTheory } from '@basis-theory/basis-theory-js';

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

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

using BasisTheory.net.Tokens;

var client = new TokenClient("key_N88mVGsp3sCXkykyN2EFED");

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

import basistheory
from basistheory.api import tokens_api

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

    tokens = tokens_client.get_children("c06d0789-0a38-40be-b7cc-c28a718f76f1")

package main

import (
  "context"
  "github.com/Basis-Theory/basistheory-go/v3"
)

func main() {
  configuration := basistheory.NewConfiguration()
  apiClient := basistheory.NewAPIClient(configuration)
  contextWithAPIKey := context.WithValue(context.Background(), basistheory.ContextAPIKeys, map[string]basistheory.APIKey{
    "ApiKey": {Key: "key_N88mVGsp3sCXkykyN2EFED"},
  })

  tokens, response, err := apiClient.TokensApi.GetChildren(contextWithAPIKey, "c06d0789-0a38-40be-b7cc-c28a718f76f1").Execute()
}

Response

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

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

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

Permissions

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

Response

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

Tokenize

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

Create Basic Token Request

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

import { BasisTheory } from '@basis-theory/basis-theory-js';

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

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

using BasisTheory.net.Tokenize;

var client = new TokenizeClient("key_N88mVGsp3sCXkykyN2EFED");

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

import basistheory
from basistheory.api import tokenize_api

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="key_N88mVGsp3sCXkykyN2EFED")) as api_client:
    tokenize_client = tokenize_api.TokenizeApi(api_client)

    token = tokenize_client.tokenize(body={
      "first_name": "John",
      "last_name": "Doe"
    })

package main

import (
  "context"
  "github.com/Basis-Theory/basistheory-go/v3"
)

func main() {
  configuration := basistheory.NewConfiguration()
  apiClient := basistheory.NewAPIClient(configuration)
  contextWithAPIKey := context.WithValue(context.Background(), basistheory.ContextAPIKeys, map[string]basistheory.APIKey{
    "ApiKey": {Key: "key_N88mVGsp3sCXkykyN2EFED"},
  })

  tokens, httpResponse, err := apiClient.TokenizeApi.Tokenize(contextWithAPIKey).Body(map[string]interface{}{
    "first_name": "John",
    "last_name": "Doe",
  }).Execute()
}

Create Basic Token Response

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

Create Token Request

curl "https://api.basistheory.com/tokenize" \
  -H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED" \
  -H "Content-Type: application/json" \
  -X "POST" \
  -d '{
    "type": "token",
    "data": "Sensitive Value",
    "metadata": {
      "nonSensitiveField": "Non-Sensitive Value"
    },
    "search_indexes": [ "{{ data }}" ],
    "fingerprint_expression": "{{ data }}"
  }'

import { BasisTheory } from '@basis-theory/basis-theory-js';

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

const token = await bt.tokenize({
  type: 'token',
  data: 'Sensitive Value',
  metadata: {
    nonSensitiveField: 'Non-Sensitive Value'
  },
  searchIndexes: [ '{{ data }}' ],
  fingerprintExpression: '{{ data }}',
});

using BasisTheory.net.Tokenize;

var client = new TokenizeClient("key_N88mVGsp3sCXkykyN2EFED");

var token = await client.Tokenize(new Token {
  Type = "token",
  Data = "Sensitive Value",
  Metadata = new Dictionary<string, string> {
    { "nonSensitiveField",  "Non-Sensitive Value" }
  },
  SearchIndexes = new List<string> {
    "{{ data }}"
  },
  FingerprintExpression = "{{ data }}" 
});

import basistheory
from basistheory.api import tokenize_api 
from basistheory.model.token import Token

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="key_N88mVGsp3sCXkykyN2EFED")) as api_client:
    tokenize_client = tokenize_api.TokenizeApi(api_client)

    token = tokenize_client.tokenize(body=Token(
      type="token",
      data="Sensitive Value",
      metadata={
        "nonSensitive": "Non-Sensitive Value"
      },
      search_indexes=[
        "{{ data }}"
      ],
      fingerprint_expression="{{ data }}"
    ))

package main

import (
  "context"
  "github.com/Basis-Theory/basistheory-go/v3"
)

func main() {
  configuration := basistheory.NewConfiguration()
  apiClient := basistheory.NewAPIClient(configuration)
  contextWithAPIKey := context.WithValue(context.Background(), basistheory.ContextAPIKeys, map[string]basistheory.APIKey{
    "ApiKey": {Key: "key_N88mVGsp3sCXkykyN2EFED"},
  })

  tokens, httpResponse, err := apiClient.TokenizeApi.Tokenize(contextWithAPIKey).Body(map[string]interface{}{
    "type": "token",
    "data": "Sensitive Value",
    "metadata": map[string]interface{}{
      "nonSensitiveField": "Non-Sensitive Value",
      },
    "search_indexes": []string{"{{ data }}"},
    "fingerprint_expression": "{{ data }}",
  }).Execute()
}

Create Token Response

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

Create Card Request

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

import { BasisTheory } from '@basis-theory/basis-theory-js';

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

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

using BasisTheory.net.Tokenize;

var client = new TokenizeClient("key_N88mVGsp3sCXkykyN2EFED");

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

import basistheory
from basistheory.api import tokenize_api 
from basistheory.model.token import Token

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="key_N88mVGsp3sCXkykyN2EFED")) as api_client:
    tokenize_client = tokenize_api.TokenizeApi(api_client)

    token = tokenize_client.tokenize(body=Token(
      type="card",
      data={
          "number": "4242424242424242",
          "expiration_month": 12,
          "expiration_year": 2025,
          "cvc": "123"
      },
      metadata={
        "nonSensitive": "Non-Sensitive Value"
      }
    ))

package main

import (
  "context"
  "github.com/Basis-Theory/basistheory-go/v3"
)

func main() {
  configuration := basistheory.NewConfiguration()
  apiClient := basistheory.NewAPIClient(configuration)
  contextWithAPIKey := context.WithValue(context.Background(), basistheory.ContextAPIKeys, map[string]basistheory.APIKey{
    "ApiKey": {Key: "key_N88mVGsp3sCXkykyN2EFED"},
  })

  tokens, httpResponse, err := apiClient.TokenizeApi.Tokenize(contextWithAPIKey).Body(map[string]interface{}{
    "type": "card",
    "data": map[string]interface{}{
      "number":           "4242424242424242",
      "expiration_month": 12,
      "expiration_year":  2025,
      "cvc":              "123",
    },
    "metadata": map[string]interface{}{
      "nonSensitiveField": "Non-Sensitive Value",
    },
  }).Execute()
}

Create Card Response

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

Tokenize Array Request

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

import { BasisTheory } from '@basis-theory/basis-theory-js';

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

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

using BasisTheory.net.Tokenize;

var client = new TokenizeClient("key_N88mVGsp3sCXkykyN2EFED");

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

import basistheory
from basistheory.api import tokenize_api
from basistheory.model.token import Token

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="key_N88mVGsp3sCXkykyN2EFED")) as api_client:
    tokenize_client = tokenize_api.TokenizeApi(api_client)

    token = tokenize_client.tokenize(body=[
        "John",
        "Doe",
        Token(
            type="card",
            data={
                "number": "4242424242424242",
                "expiration_month": 12,
                "expiration_year": 2025,
                "cvc": "123"
            },
            metadata={
                "nonSensitive": "Non-Sensitive Value"
            }
        ),
        Token(
            type="token",
            data="Sensitive Value"
        )])

package main

import (
  "context"
  "github.com/Basis-Theory/basistheory-go/v3"
)

func main() {
  configuration := basistheory.NewConfiguration()
  apiClient := basistheory.NewAPIClient(configuration)
  contextWithAPIKey := context.WithValue(context.Background(), basistheory.ContextAPIKeys, map[string]basistheory.APIKey{
    "ApiKey": {Key: "key_N88mVGsp3sCXkykyN2EFED"},
  })

  tokens, httpResponse, err := apiClient.TokenizeApi.Tokenize(contextWithAPIKey).Body(map[string]interface{}{
    "first_name": "John",
    "last_name":  "Doe",
    "card_token": map[string]interface{}{
      "type": "card",
      "data": map[string]interface{}{
        "number":           "4242424242424242",
        "expiration_month": 12,
        "expiration_year":  2025,
        "cvc":              "123",
      },
      "metadata": map[string]interface{}{
        "nonSensitiveField": "Non-Sensitive Value",
      },
    },
    "generic_token": map[string]interface{}{
      "type": "token",
      "data": "Sensitive Value",
    },
  }).Execute()
}

Tokenize Array Response

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

Composite Request

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

import { BasisTheory } from '@basis-theory/basis-theory-js';

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

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

using BasisTheory.net.Tokenize;

var client = new TokenizeClient("key_N88mVGsp3sCXkykyN2EFED");

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

import basistheory
from basistheory.api import tokenize_api
from basistheory.model.token import Token

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="key_N88mVGsp3sCXkykyN2EFED")) as api_client:
    tokenize_client = tokenize_api.TokenizeApi(api_client)

    token = tokenize_client.tokenize(body={
        "first_name": "John",
        "last_name": "Doe",
        "primary_card": Token(
            type="card",
            data={
                "number": "4242424242424242",
                "expiration_month": 12,
                "expiration_year": 2025,
                "cvc": "123"
            }),
        "sensitive_tags": [
            "preferred",
            {
                "type": "token",
                "data": "vip"
            }
        ]
    })

Composite Response

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

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

Tokenize one to many tokens for the Tenant.

Permissions

token:create

The token:create permission must be granted on each destination container, and the required scope of this permission is determined by the containers specified in the tokenize request.

Deprecations

Deprecated Endpoints

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

Endpoint	HTTP Method(s)	Deprecated	Shutdown Date	Details
`/atomic/banks/{id}/react`	`POST`	March 17, 2022	June 17, 2022	`POST /atomic/banks/{id}/react` endpoint will be removed in an upcoming release. Instead, please use Invoke a Reactor.
`/atomic/cards/{id}/react`	`POST`	March 17, 2022	June 17, 2022	`POST /atomic/cards/{id}/react` endpoint will be removed in an upcoming release. Instead, please use Invoke a Reactor.
`/tokens/decrypt`	`GET`	January 3, 2022	April 15, 2022	`GET /tokens/decrypt` endpoint will be removed in an upcoming release. Token data will now be returned based on the requester's read access. For more information, see List Tokens.
`/tokens/{id}/decrypt`	`GET`	January 3, 2022	April 15, 2022	`GET /tokens/{id}/decrypt` endpoint will be removed in an upcoming release. Token data will now be returned based on the requester's read access. For more information, see Get a Token.
`/atomic/banks/{id}/decrypt`	`GET`	January 3, 2022	April 15, 2022	`GET /atomic/banks/{id}/decrypt` endpoint will be removed in an upcoming release. Bank data will now be returned based on the requester's read access. For more information, see Get an Atomic Bank.
`/atomic/banks`	`GET`	April 3, 2022	July 8, 2022	`GET /atomic/banks` endpoint will be removed in an upcoming release. Instead, please use List Tokens.
`/atomic/banks`	`POST`	April 3, 2022	July 8, 2022	`POST /atomic/banks` endpoint will be removed in an upcoming release. Instead, please use Create Tokens.
`/atomic/banks/{id}`	`GET`	April 3, 2022	July 8, 2022	`GET /atomic/banks/{id}` endpoint will be removed in an upcoming release. Instead, please use Get a Token.
`/atomic/banks/{id}`	`PATCH`	April 3, 2022	July 8, 2022	`PATCH /atomic/banks/{id}` endpoint will be removed in an upcoming release.
`/atomic/banks/{id}`	`DELETE`	April 3, 2022	July 8, 2022	`DELETE /atomic/banks/{id}` endpoint will be removed in an upcoming release. Instead, please use Delete Token.
`/atomic/cards`	`GET`	April 3, 2022	July 8, 2022	`GET /atomic/cards` endpoint will be removed in an upcoming release. Instead, please use List Tokens.
`/atomic/cards`	`POST`	April 3, 2022	July 8, 2022	`POST /atomic/cards` endpoint will be removed in an upcoming release. Instead, please use Create Tokens.
`/atomic/cards/{id}`	`GET`	April 3, 2022	July 8, 2022	`GET /atomic/cards/{id}` endpoint will be removed in an upcoming release. Instead, please use Get a Token.
`/atomic/cards/{id}`	`PATCH`	April 3, 2022	July 8, 2022	`PATCH /atomic/cards/{id}` endpoint will be removed in an upcoming release.
`/atomic/cards/{id}`	`DELETE`	April 3, 2022	July 8, 2022	`DELETE /atomic/cards/{id}` endpoint will be removed in an upcoming release. Instead, please use Delete Token.

Deprecated Features

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

Feature	Deprecated Date	Shutdown Date	Details
`request_reactor_id` and `response_reactor_id` removed from Proxies	November 30, 2022	March 31, 2023	In order to simplify management of Proxies, use of `request_transform` and `response_tramsform` has been recommended over Reactors.
Token Privacy Settings	October 13, 2022	February 1, 2023	Privacy settings (i.e. classification, impact level, and restriction policy) have been deprecated and replaced by a more flexible authorization model based upon Containers and Access Rules. For more information, see the section below on Migrating from Privacy Settings.
`token:<classification>:*` permissions	October 13, 2022	October 13, 2022	Classification and impact level based permissions have been migrated to Access Rules to provide a more flexible model for scoping access to a subset of Tokens via Containers. For more information, see the table below.
`source_token_type` removed from Reactor Formulas	March 17, 2022	March 17, 2022	In order to support the creation of more flexible reactors that accept more than one token argument, Reactor Formulas no longer have a single `source_token_type` and this property has been removed.
`X-API-KEY` has been replaced with `BT-API-KEY`	January 9, 2022	March 9, 2022	In order to prevent potential conflicts with the `X-API-KEY` header while using the Proxy feature, the authentication header for the Basis Theory API has been replaced with `BT-API-KEY`.

Migrating From Privacy Settings

Privacy settings were previously used to scope access to Tokens based on their data classification and impact levels. In order to provide a more flexible access control model that can be customized per Application, we have introduced Token Containers to logically group Tokens according to any data governance requirements. A Token may be explicitly added to a container when creating the Token, or if unspecified, a Token will be placed within the container /<classification>/<impact_level>/ by default. If you were previously customizing a Token's classification or impact level, please update your systems to directly set the containers attribute instead.

Restriction policies were previously used in conjunction with impact level based read permissions (e.g. token:general:read:low) to define how Token data should be transformed when reading Tokens with a higher impact level than your permission allows. This model proved to be too inflexible as it was a global setting applied at the Token level and could not be customized per actor. Restriction policies no longer have any functional impact, and were replaced by transforms applied via Access Rules.

If your systems are using the privacy attribute of the Token Object in API responses, please update your integration to ignore this attribute as it will be removed on February 1, 2023.

If you were previously using classification-based Token permissions (e.g. token:general:create), your permissions have automatically been migrated to equivalent Access Rules. Refer to Migrating Permissions to Access Rules below for further details.

Migrating Permissions to Access Rules

Permissions on existing Applications have been automatically migrated to equivalent Access Rules, and no action is required. The table below details how each permission was migrated, with each row representing an Access Rule (i.e. Container, Transform, Permissions). If your authorization requirements have changed, new rules can be added, or existing rules can be removed or customized through the Portal or the API.

Legacy Permission	Container	Transform	Permission(s)
`token:general:create`	`/general/`	`mask`	`token:create`
`token:general:update`	`/general/`	`mask`	`token:update`
`token:general:read:low`	`/general/low/`	`reveal`	`token:read` `token:search`
	`/general/`	`mask`	`token:read`
`token:general:read:moderate`	`/general/low/`	`reveal`	`token:read` `token:search`
	`/general/moderate/`	`reveal`	`token:read` `token:search`
	`/general/high/`	`mask`	`token:read`
`token:general:read:high`	`/general/`	`reveal`	`token:read` `token:search`
`token:general:delete`	`/general/`	`mask`	`token:delete`
`token:general:use:proxy`	`/general/`	`reveal`	`token:use`
`token:general:use:reactor`	`/general/`	`reveal`	`token:use`
`token:bank:create`	`/bank/`	`mask`	`token:create`
`token:bank:update`	`/bank/`	`mask`	`token:update`
`token:bank:read:low`	`/bank/low/`	`reveal`	`token:read` `token:search`
	`/bank/`	`mask`	`token:read`
`token:bank:read:moderate`	`/bank/low/`	`reveal`	`token:read` `token:search`
	`/bank/moderate/`	`reveal`	`token:read` `token:search`
	`/bank/high/`	`mask`	`token:read`
`token:bank:read:high`	`/bank/`	`reveal`	`token:read` `token:search`
`token:bank:delete`	`/bank/`	`mask`	`token:delete`
`token:bank:use:proxy`	`/bank/`	`reveal`	`token:use`
`token:bank:use:reactor`	`/bank/`	`reveal`	`token:use`
`token:pci:create`	`/pci/`	`mask`	`token:create`
`token:pci:update`	`/pci/`	`mask`	`token:update`
`token:pci:read:low`	`/pci/low/`	`reveal`	`token:read` `token:search`
	`/pci/`	`mask`	`token:read`
`token:pci:read:moderate`	`/pci/low/`	`reveal`	`token:read` `token:search`
	`/pci/moderate/`	`reveal`	`token:read` `token:search`
	`/pci/high/`	`mask`	`token:read`
`token:pci:read:high`	`/pci/`	`reveal`	`token:read` `token:search`
`token:pci:delete`	`/pci/`	`mask`	`token:delete`
`token:pci:use:proxy`	`/pci/`	`reveal`	`token:use`
`token:pci:use:reactor`	`/pci/`	`reveal`	`token:use`
`token:pii:create`	`/pii/`	`mask`	`token:create`
`token:pii:update`	`/pii/`	`mask`	`token:update`
`token:pii:read:low`	`/pii/low/`	`reveal`	`token:read` `token:search`
	`/pii/`	`mask`	`token:read`
`token:pii:read:moderate`	`/pii/low/`	`reveal`	`token:read` `token:search`
	`/pii/moderate/`	`reveal`	`token:read` `token:search`
	`/pii/high/`	`mask`	`token:read`
`token:pii:read:high`	`/pii/`	`reveal`	`token:read` `token:search`
`token:pii:delete`	`/pii/`	`mask`	`token:delete`
`token:pii:use:proxy`	`/pii/`	`reveal`	`token:use`
`token:pii:use:reactor`	`/pii/`	`reveal`	`token:use`

Overview

API Endpoints

Reference

More

Introduction

What is Basis Theory?

Getting started

Before You Begin

If you don't have an account

If you have an account

Try with Postman

Install SDK

Authentication

Request Correlation

Pagination

Query Parameters

Pagination Object

Pagination Metadata Object

Errors

Response

Error Codes

Reactor Errors

Reactor Error Codes

IP Addresses

North America

Limits

Error Codes

Applications

Application Object

Application Types

Access Rules

Access Rule Transforms

Access Rule Conditions

Create Application

Permissions

Request Parameters

Response

List Applications

Permissions

Query Parameters

Response

Get an Application

Permissions

URI Parameters

Response

Get an Application by Key

Permissions

Response

Update Application

Permissions

URI Parameters

Request Parameters

Response

Regenerate API Key

Permissions

URI Parameters

Response

Delete Application

Permissions

URI Parameters

Response

Logs

Log Object

Entity Type Object

List Logs

Permissions

Query Parameters

Response

List Entity Types

Permissions

Response

Permissions

Permission Object

Permission Types

List Permissions

Query Parameters

Response

Proxy

Proxying Requests

Proxy Requests