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 |
|
401 |
Authentication Error |
|
402 |
Invalid Payment Method |
|
422 |
Unprocessable Entity |
|
429 |
Rate Limit Error |
|
500 |
Reactor Runtime Error |
|
IP Addresses
Basis Theory hosts its systems in multiple regions, but utilizes a list of static IP addresses for all oubound network traffic that your systems and firewalls can whitelist for inbound traffic. The following is a list of IP addresses by region for Basis Theory systems:
North America
- 40.77.4.67
- 40.83.13.92
- 40.122.38.216
- 104.43.246.78
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 API is granted by creating Applications, each Application type has different usages to create the most fine-grained control over your tokens and infrastructure possible. Below, we describe each Application Type and their usages.
Application Object
Attribute | Type | Description |
---|---|---|
id |
uuid | Unique identifier of the Application which can be used to get an Application |
tenant_id |
uuid | The Tenant ID which owns the Application |
name |
string | The name of the Application |
key |
string | The API key which should be used for authenticating against Basis Theory API endpoints |
type |
string | Application type of the Application |
permissions |
array | List of permissions for the Application |
created_by |
uuid | (Optional) The ID of the user or Application that created the Application |
created_at |
date | (Optional) Created date of the Application in ISO 8601 format |
modified_by |
uuid | (Optional) The ID of the user or Application that last modified the Application |
modified_at |
date | (Optional) Last modified date of the Application in ISO 8601 format |
Application Types
Name | Type | Description |
---|---|---|
Server-to-Server | server_to_server |
Used for tokenizing, retrieving, and decrypting data within backend services where the API key can be secured |
Client-side Application | public |
Used for tokenizing data directly within your mobile or browser application |
Elements | elements |
Used for tokenizing data with the Basis Theory Elements module |
Management | management |
Used for managing all aspects of your token infrastructure such as creating an Application |
Create Application
Request
curl "https://api.basistheory.com/applications" \
-H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED" \
-H "Content-Type: application/json" \
-X "POST" \
-d '{
"name": "My Example App",
"type": "server_to_server",
"permissions": [
"token:general:create",
"token:general:read:low"
"token:pci:create",
"token:pci:read:low",
]
}'
import { BasisTheory } from '@basis-theory/basis-theory-js';
const bt = await new BasisTheory().init('key_N88mVGsp3sCXkykyN2EFED');
const application = await bt.applications.create({
name: 'My Example App',
type: 'server_to_server',
permissions: [
'token:general:create',
'token:general:read:low',
'token:pci:create',
'token:pci:read:low',
],
});
using BasisTheory.net.Applications;
var client = new ApplicationClient("key_N88mVGsp3sCXkykyN2EFED");
var application = await client.CreateAsync(new Application {
Name = "My Example App",
Type = "server_to_server",
Permissions = new List<string> {
"token:general:create",
"token:general:read:low",
"token:pci:create",
"token:pci:read:low"
}
});
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="server_to_server",
permissions=[
"token:general:create",
"token:general:read:low",
"token:pci:create",
"token:pci:read:low"
]
))
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:general:create",
"token:general:read:low",
"token:pci:create",
"token:pci:read:low",
})
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": "server_to_server",
"permissions": [
"token:general:create",
"token:general:read:low",
"token:pci:create",
"token:pci:read:low"
],
"created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
"created_at": "2020-09-15T15:53:00+00:00"
}
POST
https://api.basistheory.com/applications
Create a new Application for the Tenant.
Permissions
application:create
Request Parameters
Attribute | Required | Type | Default | Description |
---|---|---|---|---|
name |
true | string | null |
The name of the Application. Has a maximum length of 200 |
type |
true | string | null |
Application type of the application |
permissions |
false | array | [] |
Permissions for the application |
Response
Returns an Application if the application was created. Returns an error if there were validation errors, or the application failed to create.
List Applications
Request
curl "https://api.basistheory.com/applications" \
-H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED"
import { BasisTheory } from '@basis-theory/basis-theory-js';
const bt = await new BasisTheory().init('key_N88mVGsp3sCXkykyN2EFED');
const applications = await bt.applications.list();
using BasisTheory.net.Applications;
var client = new ApplicationClient("key_N88mVGsp3sCXkykyN2EFED");
var applications = await client.GetAsync();
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": "server_to_server",
"permissions": [
"token:general:create",
"token:general:read:low",
"token:pci:create",
"token:pci:read:low"
],
"created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
"created_at": "2020-09-15T15:53:00+00:00",
"modified_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
"modified_at": "2021-03-01T08:23:14+00:00"
},
{...},
{...}
]
}
GET
https://api.basistheory.com/applications
Get a list of applications for the Tenant.
Permissions
application:read
Query Parameters
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
id |
false | array | [] |
An optional list of application ID's to filter the list of applications by |
Response
Returns a paginated object with the data
property containing an array of applications. Providing any query parameters will filter the results. Returns an error if applications could not be retrieved.
Get an Application
Request
curl "https://api.basistheory.com/applications/fe1f9ba4-474e-44b9-b949-110cdba9d662" \
-H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED"
import { BasisTheory } from '@basis-theory/basis-theory-js';
const bt = await new BasisTheory().init('key_N88mVGsp3sCXkykyN2EFED');
const application = await bt.applications.retrieve('fe1f9ba4-474e-44b9-b949-110cdba9d662');
using BasisTheory.net.Applications;
var client = new ApplicationClient("key_N88mVGsp3sCXkykyN2EFED");
var application = await client.GetByIdAsync("fe1f9ba4-474e-44b9-b949-110cdba9d662");
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 | [] |
Permissions for the application |
Response
Returns an Application if the application was updated. Returns an error if there were validation errors, or the application failed to update.
Regenerate API Key
Request
curl "https://api.basistheory.com/applications/fb124bba-f90d-45f0-9a59-5edca27b3b4a/regenerate" \
-H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED" \
-X "POST"
import { BasisTheory } from '@basis-theory/basis-theory-js';
const bt = await new BasisTheory().init('key_N88mVGsp3sCXkykyN2EFED');
const application = await bt.applications.regenerateKey('fb124bba-f90d-45f0-9a59-5edca27b3b4a');
using BasisTheory.net.Applications;
var client = new ApplicationClient("key_N88mVGsp3sCXkykyN2EFED");
var application = await client.RegenerateKeyAsync("fb124bba-f90d-45f0-9a59-5edca27b3b4a");
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": "server_to_server",
"permissions": [
"token:general:create",
"token:general:read:low",
"token:pci:create",
"token:pci:read:low"
],
"created_by": "c57a0d0d-e8e6-495f-9c79-a317cc21996c",
"created_at": "2020-09-15T15:53:00+00:00",
"modified_by": "a23699d2-1d55-4927-83f9-e76779f1c1c1",
"modified_at": "2021-03-01T08:23:14+00:00"
}
POST
https://api.basistheory.com/applications/{id}/regenerate
Regenerate the API key for an application.
Permissions
application:update
URI Parameters
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
id |
true | uuid | null |
The ID of the application |
Response
Returns an Application with the new key
property populated. Returns an error if there were validation errors, or the application key failed to regenerate.
Delete Application
Request
curl "https://api.basistheory.com/applications/fb124bba-f90d-45f0-9a59-5edca27b3b4a" \
-H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED" \
-X "DELETE"
import { BasisTheory } from '@basis-theory/basis-theory-js';
const bt = await new BasisTheory().init('key_N88mVGsp3sCXkykyN2EFED');
await bt.applications.delete('fb124bba-f90d-45f0-9a59-5edca27b3b4a');
using BasisTheory.net.Applications;
var client = new ApplicationClient("key_N88mVGsp3sCXkykyN2EFED");
await client.DeleteAsync("fb124bba-f90d-45f0-9a59-5edca27b3b4a");
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 aspects of your token infrastructure. We suggest limiting the scope of your Application to the least amount possible, and to not share them across your internal services.
Permissions are associated with every Application and can be configured when you create an Application or update an Application.
Every API endpoint will document the required permissions needed to perform the operation against the endpoint.
Permission Object
Attribute | Type | Description |
---|---|---|
type |
string | Permission type referenced by Basis Theory API endpoints |
description |
string | Description of the permission |
application_types |
array | List of application types that can assign the permission |
Permission Types
Management Permissions
Permission | Description | Application Types |
---|---|---|
tenant:read |
Read Tenants | management |
tenant:update |
Update Tenants | management |
tenant:delete |
Delete Tenants | management |
application:read |
Read Applications | management |
application:create |
Create Applications | management |
application:update |
Update and regenerate API keys for Applications | management |
application:delete |
Delete Applications | management |
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 |
Token Permissions
All Token permissions follow the form of token:<classification>:<operation>:<scope?>
.
Permission | Description | Application Types |
---|---|---|
token:<classification>:create |
Create Tokens in <classification> (e.g. token:general:create ) |
public , elements , server_to_server |
token:<classification>:read:low |
Read plaintext token data in <classification> with low <impact_level>. Tokens in <classification> with higher impact level will be restricted based on the token's restriction policy |
server_to_server |
token:<classification>:read:moderate |
Read plaintext token data in <classification> with moderate <impact_level> and lower. Tokens in <classification> with higher impact level will be restricted based on the token's restriction policy |
server_to_server |
token:<classification>:read:high |
Read plaintext token data in <classification> with high <impact_level> and lower (i.e. low and moderate ). |
server_to_server |
token:<classification>:update |
Update Tokens in <classification> (e.g. token:general:update ) |
server_to_server |
token:<classification>:delete |
Delete Tokens in <classification> (e.g. token:general:delete ) |
server_to_server |
token:<classification>:use:proxy |
Use Tokens in <classification> via Proxy (e.g. token:general:use:proxy ) |
server_to_server |
token:<classification>:use:reactor |
Use Tokens in <classification> via Reactor (e.g. token:general:use:reactor ) |
server_to_server |
List Permissions
Request
curl "https://api.basistheory.com/permissions" \
-H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED"
import {BasisTheory} from '@basis-theory/basis-theory-js';
const bt = await new BasisTheory().init('key_N88mVGsp3sCXkykyN2EFED');
const permissions = await bt.permissions.list();
using BasisTheory.net.Permissions;
var client = new PermissionClient("key_N88mVGsp3sCXkykyN2EFED");
var permissions = await client.GetAsync();
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:pci:read:low",
"description": "Read tokens with PCI classification of low impact level",
"application_types": [
"server_to_server"
]
},
{...},
{...}
]
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.
Proxy Requests
Request with BT-PROXY-KEY
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-URL
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
Proxy requests must be authenticated using a BT-API-KEY
header (see Authentication).
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
Depending on the classification(s) of Tokens you need to forward to a third party, the corresponding token:<classification>:use:proxy
permission is required.
At least one token:<classification>:use:proxy
permission is required, for example:
token:general:use:proxy token:pci:use:proxy token:bank:use:proxy
Configuration
Basis Theory's Proxy provides two ways to configure a request. The first option is to create a pre-configured Proxy and set the BT-PROXY-KEY
header which will route traffic to the configured destination_url
.
The alternative is to set the BT-PROXY-URL
request header. The value of the BT-PROXY-URL
header 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
.
Reactors
Basis Theory's Proxy supports executing reactors on the proxy request and response. When pre-configuring a Proxy, the request_reactor_id
and response_reactor_id
properties can optionally be set to the ID of an existing Reactor. When the request_reactor_id
property is set, this reactor 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_reactor_id
property is set, this reactor 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 reactor will receive a JSON object with the following payload:
{
args: {
body, // detokenized request body
headers // request headers
}
}
Within the reactor, the headers and body of the proxy request can be changed.
The Reactor must respond with the following object, which defines the request body
and headers
to be sent in the request to the proxy destination_url
:
{
raw: {
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 reactor. 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 {
raw {
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:<classification>:use:proxy
permission is required in order to detokenize tokens classified as <classification>
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 |
request_reactor_id |
string | The Reactor to invoke on the Proxy request |
response_reactor_id |
string | The Reactor to invoke on the Proxy response |
tenant_id |
uuid | The Tenant ID which owns the Proxy |
require_auth |
boolean | Require a BT-API-KEY request header for authentication and authorization |
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 |
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_reactor_id": "5b493235-6917-4307-906a-2cd6f1a90b13",
"response_reactor_id": "1cb923e6-ae89-407a-ba07-1564ebe99350",
"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',
requestReactorId: '5b493235-6917-4307-906a-2cd6f1a90b13',
responseReactorId: '1cb923e6-ae89-407a-ba07-1564ebe99350',
requireAuth: true
});
using BasisTheory.net.Proxies;
var client = new ProxyClient("key_N88mVGsp3sCXkykyN2EFED");
var proxy = await client.CreateAsync(new Proxy {
Name = "My Proxy",
DestinationUrl = "https://example.com/api",
RequestReactorId = "5b493235-6917-4307-906a-2cd6f1a90b13",
ResponseReactorId = "1cb923e6-ae89-407a-ba07-1564ebe99350",
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",
request_reactor_id="5b493235-6917-4307-906a-2cd6f1a90b13",
response_reactor_id="1cb923e6-ae89-407a-ba07-1564ebe99350",
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")
createProxyRequest.SetRequestReactorId("5b493235-6917-4307-906a-2cd6f1a90b13")
createProxyRequest.SetResponseReactorId("1cb923e6-ae89-407a-ba07-1564ebe99350")
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_reactor_id": "5b493235-6917-4307-906a-2cd6f1a90b13",
"response_reactor_id": "1cb923e6-ae89-407a-ba07-1564ebe99350",
"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_reactor_id |
false | string | null |
The Reactor to invoke on the Proxy request |
response_reactor_id |
false | string | null |
The Reactor to invoke on the Proxy response |
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_reactor_id": "5b493235-6917-4307-906a-2cd6f1a90b13",
"response_reactor_id": "1cb923e6-ae89-407a-ba07-1564ebe99350",
"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_reactor_id": "5b493235-6917-4307-906a-2cd6f1a90b13",
"response_reactor_id": "1cb923e6-ae89-407a-ba07-1564ebe99350",
"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_reactor_id": "5b493235-6917-4307-906a-2cd6f1a90b13",
"response_reactor_id": "1cb923e6-ae89-407a-ba07-1564ebe99350",
"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',
requestReactorId: '5b493235-6917-4307-906a-2cd6f1a90b13',
responseReactorId: '1cb923e6-ae89-407a-ba07-1564ebe99350',
requireAuth: true
});
using BasisTheory.net.Proxies;
var client = new ProxyClient("key_N88mVGsp3sCXkykyN2EFED");
var proxy = await client.UpdateAsync("433013a6-a614-4e1e-b2aa-5fba67aa85e6",
new Proxy {
Name = "My Proxy",
DestinationUrl = "https://example.com/api",
RequestReactorId = "5b493235-6917-4307-906a-2cd6f1a90b13",
ResponseReactorId = "1cb923e6-ae89-407a-ba07-1564ebe99350",
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",
request_reactor_id="5b493235-6917-4307-906a-2cd6f1a90b13",
response_reactor_id="1cb923e6-ae89-407a-ba07-1564ebe99350",
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")
updateProxyRequest.SetRequestReactorId("5b493235-6917-4307-906a-2cd6f1a90b13")
updateProxyRequest.SetResponseReactorId("1cb923e6-ae89-407a-ba07-1564ebe99350")
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_reactor_id": "5b493235-6917-4307-906a-2cd6f1a90b13",
"response_reactor_id": "1cb923e6-ae89-407a-ba07-1564ebe99350",
"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_reactor_id |
false | string | null |
The Reactor to invoke on the Proxy request |
response_reactor_id |
false | string | null |
The Reactor to invoke on the Proxy response |
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 v14) 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 permissions are 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:<classification>:use:reactor
Depending on the classification(s) of Tokens used within a Reactor, the corresponding token:<classification>:use:reactor
permission is required -
this permission grants the Reactor access to detokenize tokens of any impact level with this classification.
At least one token:<classification>:use:reactor
permission is required to invoke 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].com",
"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, data classification, data impact level, and data restriction policy.
- 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 Classification | general |
Default Impact Level | high |
Minimum Impact Level | low |
Default Restriction Policy | redact |
Input Validation | None |
Input Length | Any |
Default Fingerprint Expression | {{ data | stringify}} |
Default Mask Expression | null |
Card
Token Attribute | Value |
---|---|
Type | card |
Default Classification | pci |
Default Impact Level | high |
Minimum Impact Level | high |
Default Restriction Policy | mask |
Input Validation | See Card Object for validation requirements |
Default Fingerprint Expression | {{ data.number }} |
Default Mask Expression | { |
Bank
Token Attribute | Value |
---|---|
Type | bank |
Default Classification | bank |
Default Impact Level | high |
Minimum Impact Level | high |
Default Restriction Policy | mask |
Input Validation | See Bank Object for validation requirements |
Default Fingerprint Expression | {{ data.account_number }}|{{ data.routing_number }} |
Default Mask Expression | { |
Card Number
Token Attribute | Value |
---|---|
Type | card_number |
Default Classification | pci |
Default Impact Level | high |
Minimum Impact Level | high |
Default Restriction Policy | mask |
Input Validation | Luhn-valid, numeric |
Input Length | 13 - 19 |
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 Classification | bank |
Default Impact Level | high |
Minimum Impact Level | low |
Default Restriction Policy | mask |
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 Classification | bank |
Default Impact Level | low |
Minimum Impact Level | low |
Default Restriction Policy | redact |
Input Validation | Numeric, ABA-valid |
Input Length | 9 |
Default Fingerprint Expression | {{ data }} |
Default Mask Expression | {{ data | reveal_last: 4 }} |
Social Security Number
Token Attribute | Value |
---|---|
Type | social_security_number |
Default Classification | pii |
Default Impact Level | high |
Minimum Impact Level | low |
Default Restriction Policy | mask |
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 Classification | pii |
Default Impact Level | high |
Minimum Impact Level | low |
Default Restriction Policy | mask |
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 | (Optional) 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. |
privacy |
privacy object | Token Privacy Settings |
metadata |
map | A key-value map of non-sensitive data. |
created_by |
uuid | (Optional) The Application ID which created the token |
created_at |
date | (Optional) Created date of the token in ISO 8601 format |
modified_by |
uuid | (Optional) The Application ID which last modified the token |
modified_at |
date | (Optional) Last modified date of the token in ISO 8601 format |
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. |
Privacy Object
Token Privacy defines the privacy settings applied to a Token. By default, privacy settings will be applied based on the Token Type. Default privacy settings can be overridden at the time of creation, but only to a setting with a higher specificity level.
Attribute | Type | Description |
---|---|---|
classification |
string | Classification of the Token (e.g. general , bank , pci ) |
impact_level |
string | Impact level of the Token (i.e. low , moderate , high ) |
restriction_policy |
string | Restriction policy applied to the Token when read by a User or Application with read permissions at a lower impact level (i.e. mask , redact ) |
Token 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 Classifications
Each token has a data classification associated with it which defines the type of data it contains. Basis Theory grants access to Tokens based on data classifications (see Token Permissions for more details). The following data classifications are supported:
Name | Description | Specificity Level |
---|---|---|
general |
Contains sensitive data that does not fall under a more specific classification or compliance requirements | 0 |
bank |
Contains data that falls under banking compliance (e.g. Nacha) | 10 |
pci |
Contains data that falls under PCI compliance | 10 |
pii |
Contains user or customer specific identifiers (e.g. email, date of birth, address) | 10 |
Token Impact Levels
Basis Theory follows the standard NIST-defined impact levels of low, moderate, and high to classify the impact unauthorized exposure of a particular piece of data would have on an organization. Token impact levels are used to further classify and permit access to Tokens within a Token Classification.
Name | Description | Specificity Level |
---|---|---|
low |
Loss of data confidentiality, integrity, or availability is expected to have limited adverse effect | 0 |
moderate |
Loss of data confidentiality, integrity, or availability is expected to have serious adverse effect | 1 |
high |
Loss of data confidentiality, integrity, or availability is expected to have severe or catastrophic adverse effect | 2 |
Token Restriction Policies
A Token Restriction Policy defines the policy to enforce on a Token's data when read by a User or Application with permission to read the Token's classification but at a lower impact level.
Name | Description | Specificity Level |
---|---|---|
mask |
Token data will be masked in the response, falling back to redact restriction policy if a mask is not available for the Token Type |
0 |
redact |
Token data will be completely removed in the response | 1 |
For example, an application with token:pci:read:low
is allowed to read a card_number
token (classified as pci
with high
impact level),
but the plaintext card data will not be returned. Instead, the restriction policy associated with the card_number
token (mask
) will be applied and only masked card number data will be returned.
Refer to mask expressions to find out more about how to define masks for your token data.
Token Expiration
By default a created token will not expire, however, users can optionally set the expires_at
property 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 }}",
"privacy": {
"restriction_policy": "mask"
},
"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 }}',
privacy: {
restriction_policy: 'mask'
},
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 }}",
Privacy = new DataPrivacy {
RestrictionPolicy = DataRestrictionPolicy.MASK
},
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"
},
privacy=Privacy(
restriction_policy="mask"
),
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.SetExpiresAt("8/26/2030 7:23:57 PM -07:00")
privacy := *basistheory.NewPrivacy()
privacy.SetRestrictionPolicy("mask")
createTokenRequest.SetPrivacy(privacy)
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 }}",
"privacy": {
"classification": "general",
"impact_level": "high",
"restriction_policy": "mask"
},
"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:<classification>: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. |
privacy |
false | privacy object | null |
Token Privacy Settings overrides. Overrides must be a higher specificity level than the default or minimum setting for the Token Type. |
metadata |
false | map | null |
A key-value map of non-sensitive data. |
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 |
Token expiration date/time. 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": null, // Redacted based on Restriction Policy
"privacy": {
"classification": "general",
"impact_level": "moderate",
"restriction_policy": "redact"
},
"metadata": {
"nonSensitiveField": "Non-Sensitive Value"
},
"created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
"created_at": "2021-03-01T08:23:14+00:00"
},
{...},
{...}
]
}
GET
https://api.basistheory.com/tokens
Get a list of tokens for the Tenant, supporting basic search criteria. If you need to perform a more advanced token search, see Search Tokens.
Permissions
token:<classification>:read:<impact_level>
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.
Plaintext token data will be returned when the requester has read permissions on the token classification at equal or greater impact level.
Token data will be restricted based on the token's restriction policy when the requester has read permissions on the token classification at a lower impact level.
Providing any query parameters will filter the results. Returns an error if tokens could not be retrieved.
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": null, // Redacted based on Restriction Policy
"privacy": {
"classification": "general",
"impact_level": "moderate",
"restriction_policy": "redact"
},
"metadata": {
"nonSensitiveField": "Non-Sensitive Value"
},
"created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
"created_at": "2021-03-01T08:23:14+00:00"
}
GET
https://api.basistheory.com/tokens/{id}
Get a token by ID in the Tenant.
Permissions
token:<classification>:read:<impact_level>
URI Parameters
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
id |
true | string | null |
The ID of the token |
Response
Returns a token with the id
provided.
Plaintext token data will be returned when the requester has read permissions on the token classification at equal or greater impact level.
Token data will be restricted based on the token's restriction policy when the requester has read permissions on the token classification at a lower impact level.
Returns an error if the token could not be retrieved.
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 }}",
"privacy": {
"restriction_policy": "mask"
},
"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 }}',
privacy: {
restrictionPolicy: "mask"
},
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 }}",
Privacy = new PrivacyUpdateModel {
RestrictionPolicy = DataRestrictionPolicy.MASK
},
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"
},
privacy=UpdatePrivacy(
restriction_policy="mask"
),
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 }}")
privacy := *basistheory.NewPrivacy()
privacy.SetRestrictionPolicy("mask")
updateTokenRequest.SetPrivacy(privacy)
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 }}",
"privacy": {
"classification": "general",
"impact_level": "high",
"restriction_policy": "mask"
},
"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:<classification>: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. |
privacy |
false | privacy object | Replace | Token Privacy Settings overrides. Overrides must be a higher specificity level than the default or minimum setting for the Token Type. The classfication attribute of the privacy object cannot be overriden on update. |
metadata |
false | map | Merge Patch (see RFC 7386) | A key-value map of non-sensitive data. |
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",
"privacy": {
"classification": "pii",
"impact_level": "high",
"restriction_policy": "mask"
},
"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:<classification>:read:<impact_level>
At least one token read permission is required in order to perform a token search. A token search will only return tokens that your application or user is authorized to read.
Applications are permitted to search on the data
field of a token only if the application's permissions
allow reading the unrestricted plaintext token data.
Applications may search across non-data fields (eg. metadata
, type
) on tokens with any read permission for that data classification, even if that read permission only allows restricted access to the token data.
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.
Plaintext token data will be returned when the requester has read permissions on the token classification at equal or greater impact level.
Token data will be restricted based on the token's restriction policy when the requester has read permissions on the token classification at a lower impact level.
Returns an error if 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
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 |
privacy.[field] |
string | Token privacy settings. | privacy.classification:pci |
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:<classification>: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 the appropriate read permission based on the parent and child tokens' privacy settings.
token:<classification>:read:<impact_level>
URI Parameters
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
parent_id |
true | 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:<classification>: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",
"privacy": {
"classification": "general",
"impact_level": "high",
"restriction_policy": "redact"
},
"created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
"created_at": "2020-09-15T15:53:00+00:00",
"metadata": {
"nonSensitiveField": "Non-Sensitive Value"
}
}
POST
https://api.basistheory.com/tokens/{parent_id}/children
Create a new child token a token in the Tenant.
Permissions
Creating a child token requires the appropriate create permission based on the child's classification as well as the appropriate read
permission based on the parent token's privacy settings.
token:<classification>:create token:<classification>:read:<impact_level>
URI Parameters
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
parent_id |
true | string | null |
The ID of the parent token |
Request Parameters
Attribute | Required | Type | Default | Description |
---|---|---|---|---|
type |
true | string | null |
Token type of the token |
data |
true | any | null |
Token data |
privacy |
false | privacy object | null |
Token Privacy Settings |
metadata |
false | map | null |
A key-value map of non-sensitive data. |
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": null, // Redacted based on restriction policy
"privacy": {
"classification": "general",
"impact_level": "high",
"restriction_policy": "redact"
},
"metadata": {
"nonSensitiveField": "Non-Sensitive Value"
},
"created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
"created_at": "2021-03-01T08:23:14+00:00"
},
{...},
{...}
]
}
GET
https://api.basistheory.com/tokens/{parent_id}/children
Get a list of child tokens for a token in the Tenant.
Permissions
token:<classification>:read:<impact_level>
URI Parameters
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
parent_id |
true | string | null |
The ID of the parent token |
Query Parameters
Parameter | Required | Type | Default | Description |
---|---|---|---|---|
id |
false | array | [] |
An optional list of token ID's to filter the list of child tokens by |
type |
false | array | [] |
An optional array of token types to filter the list of child tokens by |
Response
Returns a paginated object with the data
property containing an array of child tokens for the parent token. Providing any query parameters will filter the child tokens. Returns an error if tokens could not be retrieved.
Tokenize
The tokenize
endpoint enables you to tokenize any request and tokenize several types of tokens in the same request. It can be utilized to combine multiple API calls into a single request to match your current data structure or bulk token creation.
Create Basic Token Request
curl "https://api.basistheory.com/tokenize" \
-H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED" \
-H "Content-Type: application/json" \
-X "POST" \
-d '{
"first_name": "John",
"last_name": "Doe"
}'
import { BasisTheory } from '@basis-theory/basis-theory-js';
const bt = await new BasisTheory().init('key_N88mVGsp3sCXkykyN2EFED');
const token = await bt.tokenize({
first_name: 'John',
last_name: 'Doe'
});
using BasisTheory.net.Tokenize;
var client = new TokenizeClient("key_N88mVGsp3sCXkykyN2EFED");
var token = await client.Tokenize(new {
first_name = "John",
last_name = "Doe"
});
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
Permissions are determined by the classification(s) being tokenized and require the appropriate token:<classification>:create
permission(s) based on the request.
Deprecations
Deprecated Endpoints
The following table lists deprecated API endpoints and their respective shutdown date.
Endpoint | HTTP Method(s) | Deprecated | Shutdown Date | Details |
---|---|---|---|---|
/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 date.
Feature | Deprecated | Shutdown Date | Details | ||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
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 . |
||||||||||||||||||||||||||||||||||||
token:* , bank:* and card:* permissions |
January 3, 2022 | January 3, 2022 | The following permissions have been removed as of January 3, 2022 (see table for removed permissions and their replacement). New token permissions provide more granular access control based on Data Classification and Impact Level. For more information, see Token Permissions.
|