Applications

Applications play a crucial role in facilitating systems' authentication to Basis Theory. They determine the extent of access granted to individual systems and manage Application Keys, which serve as the means for API Authentication. Each type of Application supports different use cases, and it's important to allocate access levels judiciously for each Application. Below, we provide a description of each Application Type and guidance on selecting the appropriate one for your needs

Create Application

Create a new Application for the Tenant.

POST

https://api.basistheory.com/applications

Permissions

application:create

Request

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

const application = await managementClient.applications.create({
    type: '...',
    name: '...',
    permissions: ['...']
    ...
});

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

const bt = await new BasisTheory().init("<MANAGEMENT_API_KEY>");

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

await client.Applications.CreateAsync(
    new CreateApplicationRequest { Name = "name", Type = "type" }
);

client.applications.create(
    name="name",
    type="type",
    ...
)

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	`null`	ISO8601 compatible DateTime in which the application will be deleted
`create_key`	false	boolean	`true`	When `true` will create an Application Key

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": "<PRIVATE_API_KEY>",
  "keys": [],
  "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 "https://api.basistheory.com/applications" \
  -H "BT-API-KEY: <MANAGEMENT_API_KEY>"

const response = await client.applications.list();
for await (const item of response) {
    console.log(item);
}

// Or you can manually iterate page-by-page
const page = await client.applications.list();
while (page.hasNextPage()) {
    page = page.getNextPage();
}

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

const bt = await new BasisTheory().init("<MANAGEMENT_API_KEY>");

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

await client.Applications.ListAsync(new ApplicationsListRequest());

response = client.applications.list()
for item in response:
    yield item

# alternatively, you can paginate page-by-page
for page in response.iter_pages():
    yield page

Query Parameters

Parameter	Required	Type	Default	Description
`id`	false	array	`[]`	An optional list of application IDs 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",
      "keys": [],
      "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 "https://api.basistheory.com/applications/fe1f9ba4-474e-44b9-b949-110cdba9d662" \
  -H "BT-API-KEY: <MANAGEMENT_API_KEY>"

await client.applications.get("id");

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

const bt = await new BasisTheory().init("<MANAGEMENT_API_KEY>");

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

await client.Applications.GetAsync("id");

client.applications.get(
    id="id",
)

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",
  "keys": [],
  "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 "https://api.basistheory.com/applications/key" \
  -H "BT-API-KEY: <MANAGEMENT_API_KEY>"

await client.applications.getByKey();

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

const bt = await new BasisTheory().init("<MANAGEMENT_API_KEY>");

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

await client.Applications.GetByKeyAsync();

client.applications.get_by_key()

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",
  "keys": [],
  "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 "https://api.basistheory.com/applications/fb124bba-f90d-45f0-9a59-5edca27b3b4a" \
  -H "BT-API-KEY: <MANAGEMENT_API_KEY>" \
  -H "Content-Type: application/json"
  -X "PUT" \
  -d '{
    "name": "My Example App",
    "permissions": [
      "application:create",
      "application:read"
    ]
  }'

await client.applications.update("id", {
    name: "name",
    ...
});

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

const bt = await new BasisTheory().init("<MANAGEMENT_API_KEY>");

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

await client.Applications.UpdateAsync("id", new UpdateApplicationRequest { Name = "name" });

client.applications.update(
    id="id",
    name="name",
)

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.

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",
  "keys": [],
  "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"
}

Delete Application

Delete an application by ID in the Tenant.

DELETE

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

Permissions

application:delete

Request

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

await client.applications.delete("id");

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

const bt = await new BasisTheory().init("<MANAGEMENT_API_KEY>");

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

await client.Applications.DeleteAsync("id");

client.applications.delete(
    id="id",
)

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	Key of the Application Key created when `create_key = true` on Create Application.
`keys`	array	The Application Keys associated with the Application
`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

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 collecting data within your mobile or browser application
Management	`management`	Used for managing all aspects of your infrastructure such as creating an 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 applies to sessions
`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 private applications, whilst conditions is only required for sessions. 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

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​

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

Delete Application

Permissions

Request

URI Parameters

Response

Application Object

Application Types

Access Rules

Access Rule Transforms

Access Rule Conditions