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

JavaScript

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

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

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

C#

using BasisTheory.net.Tenants;

var client = new TenantClient("<MANAGEMENT_API_KEY>");

var tenant = await client.GetSelfAsync();

Java

import com.basistheory.*;
import com.basistheory.auth.*;

public class App {
    public static void main(String[] args) throws Exception {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        defaultClient.setBasePath("https://api.basistheory.com");

        ApiKeyAuth ApiKey = (ApiKeyAuth) defaultClient.getAuthentication("ApiKey");
        ApiKey.setApiKey("<MANAGEMENT_API_KEY>);

        TenantsApi apiInstance = new TenantsApi(defaultClient);
        Tenant result = apiInstance.get();
    }
}

Python

import basistheory
from basistheory.api import tenants_api

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="<MANAGEMENT_API_KEY>")) as api_client:
    tenants_client = tenants_api.TenantsApi(api_client)

    tenant = tenants_client.get()

Go

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: "<MANAGEMENT_API_KEY>"},
  })

  tenant, httpResponse, err := apiClient.TenantsApi.Get(contextWithAPIKey).Execute()
}

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

JavaScript

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#

using BasisTheory.net.Tenants;

var client = new TenantClient("<MANAGEMENT_API_KEY>");

var tenant = await client.UpdateAsync(new TenantUpdateRequest
{
  Name = "My Example Tenant",
  Settings = new Dictionary<string, string>
  {
    { "fingerprint_tokens", "true" },
    { "disable_ephemeral_proxy", "true" },
    { "deduplicate_tokens", "true" }
  }
});

Java

import com.basistheory.*;
import com.basistheory.auth.*;

public class App {
    public static void main(String[] args) throws Exception {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        defaultClient.setBasePath("https://api.basistheory.com");

        ApiKeyAuth ApiKey = (ApiKeyAuth) defaultClient.getAuthentication("ApiKey");
        ApiKey.setApiKey("<MANAGEMENT_API_KEY>");

        TenantsApi apiInstance = new TenantsApi(defaultClient);
        UpdateTenantRequest updateTenantRequest = new UpdateTenantRequest(); // UpdateTenantRequest |
        Tenant result = apiInstance.update(updateTenantRequest.name("My Example Tenant"));
    }
}

Python

import basistheory
from basistheory.api import tenants_api
from basistheory.model.update_tenant_request import UpdateTenantRequest

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="<MANAGEMENT_API_KEY>")) as api_client:
    tenants_client = tenants_api.TenantsApi(api_client)

    tenant = tenants_client.update(update_tenant_request=UpdateTenantRequest(
        name="My Example Tenant"
    ))

Go

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: "<MANAGEMENT_API_KEY>"},
  })

  updateTenantRequest := *basistheory.NewUpdateTenantRequest("My Example Tenant")
  updateTenantRequest.SetSettings(map[string]string{
    "fingerprint_tokens": "true",
    "disable_ephemeral_proxy": "true",
    "deduplicate_tokens": "true",
  })

  tenant, httpResponse, err := apiClient.TenantsApi.Update(contextWithAPIKey).UpdateTenantRequest(updateTenantRequest).Execute()
}

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

Permissions

tenant:delete

Request

cURL

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

JavaScript

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

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

await bt.tenants.delete();

C#

using BasisTheory.net.Tenants;

var client = new TenantClient("<MANAGEMENT_API_KEY>");

await client.DeleteAsync();

Java

import com.basistheory.*;
import com.basistheory.auth.*;

public class App {
    public static void main(String[] args) throws Exception {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        defaultClient.setBasePath("https://api.basistheory.com");

        ApiKeyAuth ApiKey = (ApiKeyAuth) defaultClient.getAuthentication("ApiKey");
        ApiKey.setApiKey("<MANAGEMENT_API_KEY>");

        TenantsApi apiInstance = new TenantsApi(defaultClient);
        apiInstance.delete();
    }
}

Python

import basistheory
from basistheory.api import tenants_api

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="<MANAGEMENT_API_KEY>")) as api_client:
    tenants_client = tenants_api.TenantsApi(api_client)

    tenants_client.delete()

Go

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: "<MANAGEMENT_API_KEY>"},
  })

  httpResponse, err := apiClient.TenantsApi.Delete(contextWithAPIKey).Execute()
}

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

JavaScript

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

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

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

C#

using BasisTheory.net.Tenants;

var client = new TenantClient("<MANAGEMENT_API_KEY>");

var tenantUsageReport = await client.GetTenantUsageReportAsync();

Java

import com.basistheory.*;
import com.basistheory.auth.*;

public class App {
    public static void main(String[] args) throws Exception {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        defaultClient.setBasePath("https://api.basistheory.com");

        ApiKeyAuth ApiKey = (ApiKeyAuth) defaultClient.getAuthentication("ApiKey");
        ApiKey.setApiKey("<MANAGEMENT_API_KEY>");

        TenantsApi apiInstance = new TenantsApi(defaultClient);
        TenantUsageReport result = apiInstance.getTenantUsageReport();
    }
}

Python

import basistheory
from basistheory.api import tenants_api

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="<MANAGEMENT_API_KEY>")) as api_client:
    tenants_client = tenants_api.TenantsApi(api_client)

    tenant_usage_report = tenants_client.get_tenant_usage_report()

Go

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: "<MANAGEMENT_API_KEY>"},
  })

  tenantUsageReport, httpResponse, err := apiClient.TenantsApi.GetTenantUsageReport(contextWithAPIKey).Execute()
}

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

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