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.

Get a Tenant

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

GET

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

Permissions

tenant:read

Request

cURL

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

Node

await client.tenants.self.get();

JavaScript (legacy)

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

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

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

C#

await client.Tenants.Self.GetAsync();

Java

Tenant tenant = new TenantsClient(ClientOptions.builder().build())
    .self()
    .get();

Python

client.tenants.self_.get()

Go

tenant, err := client.Tenants.Self.Get(ctx)

Response

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

{
  "id": "f88da999-b124-4a14-acde-cbc121444f14",
  "owner_id": "97cec6e8-a143-4fb4-9ab0-cf7e49242d21",
  "name": "My Tenant",
  "type": "production",
  "settings": {
    "fingerprint_tokens": "false",
    "disable_ephemeral_proxy": "false",
    "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"
}

Update Tenant

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

PUT

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

Permissions

tenant:update

Request

cURL

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

Node

await client.tenants.self.update({
    name: "name",
});

JavaScript (legacy)

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

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

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

C#

await client.Tenants.Self.UpdateAsync(new UpdateTenantRequest { Name = "name" });

Java

Tenant updatedTenant = new TenantsClient(ClientOptions.builder().build())
    .self()
    .update(UpdateTenantRequest.builder()
        .name("My Example Tenant")
        .build());

Python

client.tenants.self_.update(
    name="name",
)

Go

tenant, err := client.Tenants.Self.Update(ctx, &tenants.UpdateTenantRequest{
    Name: "My Example Tenant",
})

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.

{
  "id": "f88da999-b124-4a14-acde-cbc121444f14",
  "owner_id": "97cec6e8-a143-4fb4-9ab0-cf7e49242d21",
  "name": "My Example Tenant",
  "type": "production",
  "settings": {
    "fingerprint_tokens": "true",
    "disable_ephemeral_proxy": "true",
    "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"
}

Get Security Contact Email

Retrieves the security contact email used for vulnerability notifications.

If a security contact email is not configured, this endpoint returns the tenant owner email.

For notification cadence and event behavior, see Runtime Vulnerability Scanning.

GET

https://api.basistheory.com/tenants/self/security-contact

Permissions

tenant:read

Request

cURL

curl "https://api.basistheory.com/tenants/self/security-contact" \
  -H "BT-API-KEY: <MANAGEMENT_API_KEY>"

Node

await client.tenants.securityContact.get();

JavaScript (legacy)

const response = await fetch("https://api.basistheory.com/tenants/self/security-contact", {
  method: "GET",
  headers: {
    "BT-API-KEY": "<MANAGEMENT_API_KEY>",
  },
});

const securityContact = await response.json();

C#

await client.Tenants.SecurityContact.GetAsync();

Java

SecurityContactEmailResponse securityContact = new TenantsClient(ClientOptions.builder().build())
    .securityContact()
    .get();

Python

client.tenants.security_contact.get()

Go

securityContact, err := client.Tenants.SecurityContact.Get(ctx)

Response

Returns a security contact object for the provided BT-API-KEY.

{
  "email": "security@example.com"
}

Update Security Contact Email

Updates the security contact email used for vulnerability notifications.

PUT

https://api.basistheory.com/tenants/self/security-contact

Permissions

tenant:update

Request

cURL

curl "https://api.basistheory.com/tenants/self/security-contact" \
  -H "BT-API-KEY: <MANAGEMENT_API_KEY>" \
  -H "Content-Type: application/json" \
  -X "PUT" \
  -d '{
    "email": "security@example.com"
  }'

Node

await client.tenants.securityContact.update({
  email: "security@example.com",
});

JavaScript (legacy)

const response = await fetch("https://api.basistheory.com/tenants/self/security-contact", {
  method: "PUT",
  headers: {
    "BT-API-KEY": "<MANAGEMENT_API_KEY>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    email: "security@example.com",
  }),
});

const securityContact = await response.json();

C#

await client.Tenants.SecurityContact.UpdateAsync(new SecurityContactEmailRequest
{
    Email = "security@example.com"
});

Java

SecurityContactEmailResponse securityContact = new TenantsClient(ClientOptions.builder().build())
    .securityContact()
    .update(SecurityContactEmailRequest.builder()
        .email("security@example.com")
        .build());

Python

client.tenants.security_contact.update(
    email="security@example.com",
)

Go

securityContact, err := client.Tenants.SecurityContact.Update(ctx, &tenants.SecurityContactEmailRequest{
    Email: "security@example.com",
})

Request Parameters

Attribute	Required	Type	Description
email	true	string	Security contact email address. Max length 200 characters.

Response

Returns the updated security contact object.

{
  "email": "security@example.com"
}

Delete Tenant

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

DELETE

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

Permissions

tenant:delete

Request

cURL

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

Node

await client.tenants.self.delete();

JavaScript (legacy)

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

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

await bt.tenants.delete();

C#

await client.Tenants.Self.DeleteAsync();

Java

new TenantsClient(ClientOptions.builder().build())
   .self()
    .delete();

Python

client.tenants.self_.delete()

Go

err := client.Tenants.Self.Delete(ctx)

Response

Returns an error if the Tenant failed to delete.

Get Tenant Usage Report

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

GET

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

Permissions

report:read

Request

cURL

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

Node

await client.tenants.self.getUsageReports();

JavaScript (legacy)

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

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

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

C#

await client.Tenants.Self.GetUsageReportsAsync();

Java

TenantUsageReport report = new TenantsClient(ClientOptions.builder().build())
    .self()
    .getUsageReports();

Python

client.tenants.self_.get_usage_reports()

Go

report, err := client.Tenants.Self.GetUsageReports(ctx)

Response

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

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

Tenant Object

Attribute	Type	Description
id	uuid	Unique identifier of the Tenant
owner_id	uuid	The user ID which owns the Tenant
type	string	The type of the Tenant: production or test
name	string	The name of the Tenant
settings	Tenant Settings	The settings 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 Settings Object

Attribute	Type	Description
fingerprint_tokens	string	(Bool) Whether all tokens will be fingerprinted using the default fingerprint expression for its token type. When disabled, fingerprinting can still be enabled per token by setting a fingerprint expression on the token.
disable_ephemeral_proxy	string	(Bool) When true, ephemeral proxies will not be allowed for the tenant.
deduplicate_tokens	string	(Bool) Whether tokens are deduplicated on creation and updates.
token_deduplication_behavior	string	Whether existing tokens have their data updated to the incoming token (update_existing) or remain unchanged and returned as is (read_existing) on deduplication. Token Intents do not use this setting and are always deduplicated when converting to tokens with the update_existing behavior.

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

To learn more about pricing, check out our pricing page.

Token Type Metrics Object

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