Skip to main content

Applications

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

Create Application

Create a new Application for the Tenant.

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

Permissions

application:create

Request

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

Request Parameters

AttributeRequiredTypeDefaultDescription
nametruestringnullThe name of the Application. Has a maximum length of 200
typetruestringnullApplication type of the application
permissionsfalsearray[]An array of Permissions granted to the application
rulesfalsearray[]An array of Access Rules granted to the application
expires_atfalsestringnullISO8601 compatible DateTime in which the application will be deleted

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

Response

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

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

List Applications

Get a list of applications for the Tenant.

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

Permissions

application:read

Request

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

Query Parameters

ParameterRequiredTypeDefaultDescription
idfalsearray[]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.

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

Get an Application

Get an application by ID in the Tenant.

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

Permissions

application:read

Request

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

URI Parameters

ParameterRequiredTypeDefaultDescription
idtrueuuidnullThe ID of the application

Response

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

{
"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 an Application by Key

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

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

Permissions

application:read

Request

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

Response

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

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

Update Application

Update an application by ID in the Tenant.

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

Permissions

application:update

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

URI Parameters

ParameterRequiredTypeDefaultDescription
idtrueuuidnullThe ID of the application

Request Parameters

AttributeRequiredTypeDefaultDescription
nametruestringnullThe name of the application. Has a maximum length of 200
permissionsfalsearray[]A non-empty array of Permissions granted to the application.
rulesfalsearray[]An array of Access Rules granted to the application.

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

Response

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

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

Regenerate API Key

Regenerate the API key for an application.

POST
https://api.basistheory.com/applications/{id}/regenerate
Copy
Regenerating the API key for an application will immediately invalidate the previous API key associated with the application.

Permissions

application:update

Request

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

URI Parameters

ParameterRequiredTypeDefaultDescription
idtrueuuidnullThe 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.

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

Delete Application

Delete an application by ID in the Tenant.

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

Permissions

application:delete

Request

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

URI Parameters

ParameterRequiredTypeDefaultDescription
idtrueuuidnullThe ID of the application

Response

Returns an error if the application failed to delete.

Application Object

AttributeTypeDescription
iduuidUnique identifier of the Application which can be used to get an Application
tenant_iduuidThe Tenant ID which owns the Application
namestringThe name of the Application
keystringThe API key which should be used for authenticating against Basis Theory API endpoints
typestringApplication type of the Application
permissionsarrayList of permissions granted to the Application
rulesarrayList of access rules granted to the Application
created_byuuid(Optional) The ID of the user or Application that created the Application
created_atdate(Optional) Created date of the Application in ISO 8601 format
modified_byuuid(Optional) The ID of the user or Application that last modified the Application
modified_atdate(Optional) Last modified date of the Application in ISO 8601 format
expires_atdate(Optional) Expiring date of the Application in ISO 8601 format

Application Types

NameTypeDescription
PrivateprivateUsed for tokenizing, retrieving, and decrypting data within backend services where the API key can be secured
PublicpublicUsed for collecting data within your mobile or browser application
ManagementmanagementUsed for managing all aspects of your infrastructure such as creating an Application

Access Rules

AttributeTypeDescription
descriptionstringA description of this Access Rule
priorityintThe priority of the rule, beginning with 1 and higher values having lower precedence
containerstring(Optional) The container of Tokens this rule is scoped to
conditionsarray(Optional) List of conditions to be satisfied for the rule to be used. Only apply to sessions
transformstringThe transform to apply to accessed Tokens
permissionsarrayList of permissions to grant on this Access Rule

See Access Rules for more information.

container is only required for public and privateapplications, whilst conditions is only required for sessions. They are mutually exclusive.

Access Rule Transforms

NameTypeDescription
RedactredactRedacts the data property from Token responses
MaskmaskReturns the masked value in the data property on Token responses if a mask is defined, otherwise data is redacted
RevealrevealReturns the plaintext value in the data property in Token responses

Access Rule Conditions

AttributeTypeDescription
attributestringThe token attribute the condition is evaluated on. Either id or container
operatorstringThe operator used for the evaluation. Either starts_with or equals
valuestringThe value to evaluate against the token attribute