Applications

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

Create Application

Create a new Application for the Tenant.

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

Permissions

application:create

Request

cURL
JavaScript
C#
Python
Go

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

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

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

const application = await bt.applications.create({
  name: "My Example App",
  type: "private",
  permissions: ["token:create", "token:read"],
});

using BasisTheory.net.Applications;

var client = new ApplicationClient("key_N88mVGsp3sCXkykyN2EFED");

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

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

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

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

package main

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

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

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

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

Request Parameters

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

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

Response

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

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

Permissions

application:read

Request

cURL
JavaScript
C#
Python
Go

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()
}

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.

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

Permissions

application:read

Request

cURL
JavaScript
C#
Python
Go

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()
}

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.

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

Permissions

application:read

Request

cURL
JavaScript
C#
Python
Go

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

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}

Permissions

application:update

Request

cURL
JavaScript
C#
Python
Go

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()
}

URI Parameters

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

Request Parameters

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

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

Response

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

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

Regenerating the API key for an application will immediately invalidate the previous API key associated with the application.

Permissions

application:update

Request

cURL
JavaScript
C#
Python
Go

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()
}

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.

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

Permissions

application:delete

Request

cURL
JavaScript
C#
Python
Go

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()
}

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.

Application Object

Attribute	Type	Description
`id`	uuid	Unique identifier of the Application which can be used to get an Application
`tenant_id`	uuid	The Tenant ID which owns the Application
`name`	string	The name of the Application
`key`	string	The API key which should be used for authenticating against Basis Theory API endpoints
`type`	string	Application type of the Application
`permissions`	array	List of permissions granted to the Application
`rules`	array	List of access rules granted to the Application
`created_by`	uuid	(Optional) The ID of the user or Application that created the Application
`created_at`	date	(Optional) Created date of the Application in ISO 8601 format
`modified_by`	uuid	(Optional) The ID of the user or Application that last modified the Application
`modified_at`	date	(Optional) Last modified date of the Application in ISO 8601 format
`expires_at`	date	(Optional) Expiring date of the Application in ISO 8601 format
`can_create_expiring_applications`	bool	(Optional) Whether this application can provision Expiring applications

Application Types

Name	Type	Description
Private	`private`	Used for tokenizing, retrieving, and decrypting data within backend services where the `API key` can be secured
Public	`public`	Used for tokenizing data directly within your mobile or browser application
Management	`management`	Used for managing all aspects of your token infrastructure such as creating an Application
Expiring	`expiring`	Used for revealing sensitive data using elements within your mobile or browser application

Access Rules

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

See Access Rules for more information.

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

Access Rule Transforms

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

Access Rule Conditions

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

Applications

Create Application​

Permissions​

Request​

Request Parameters​

Response​

List Applications​

Permissions​

Request​

Query Parameters​

Response​

Get an Application​

Permissions​

Request​

URI Parameters​

Response​

Get an Application by Key​

Permissions​

Request​

Response​

Update Application​

Permissions​

Request​

URI Parameters​

Request Parameters​

Response​

Regenerate API Key​

Permissions​

Request​

URI Parameters​

Response​

Delete Application​

Permissions​

Request​

URI Parameters​

Response​

Application Object​

Application Types​

Access Rules​

Access Rule Transforms​

Access Rule Conditions​

Create Application

Permissions

Request

Request Parameters

Response

List Applications

Permissions

Request

Query Parameters

Response

Get an Application

Permissions

Request

URI Parameters

Response

Get an Application by Key

Permissions

Request

Response

Update Application

Permissions

Request

URI Parameters

Request Parameters

Response

Regenerate API Key

Permissions

Request

URI Parameters

Response

Delete Application

Permissions

Request

URI Parameters

Response

Application Object

Application Types

Access Rules

Access Rule Transforms

Access Rule Conditions