Skip to main content

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
Copy

Permissions

tenant:read

Request

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

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
Copy

Permissions

tenant:update

Request

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

Request Parameters

AttributeRequiredTypeDefaultDescription
nametruestringnullThe name of the Tenant. Has a maximum length of 200
settingsfalsestringTenant SettingsThe 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"
}

Delete Tenant

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

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

Permissions

tenant:delete

Request

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

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
Copy

Permissions

report:read

Request

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

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

AttributeTypeDescription
iduuidUnique identifier of the Tenant
owner_iduuidThe user ID which owns the Tenant
typestringThe type of the Tenant: production or test
namestringThe name of the Tenant
settingsTenant SettingsThe settings for the Tenant
created_byuuid(Optional) The ID of the user that created the Tenant
created_atdate(Optional) Created date of the Tenant in ISO 8601 format
modified_byuuid(Optional) The ID of the user or Application that last modified the Tenant
modified_atdate(Optional) Last modified date of the Tenant in ISO 8601 format

Tenant Settings Object

AttributeTypeDescription
fingerprint_tokensstring(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_proxystring(Bool) When true, ephemeral proxies will not be allowed for the tenant.
deduplicate_tokensstring(Bool) Whether tokens are deduplicated on creation and updates

Tenant Usage Report Object

AttributeTypeDescription
token_reportToken ReportToken Usage Report for Tenant

Token Report Object

AttributeTypeDescription
metrics_by_typemap<string, TokenTypeMetrics>Token Metrics by TokenType
included_monthly_active_tokenslongNumber of included monthly active tokens for the billing plan
monthly_active_tokenslongNumber 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

AttributeTypeDescription
countlongNumber of tokens
last_created_atdate(Optional) Last created date in ISO 8601 format