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 "https://api.basistheory.com/tenants/self" \
  -H "BT-API-KEY: <MANAGEMENT_API_KEY>"

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

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

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

using BasisTheory.net.Api;
using BasisTheory.net.Client;
using BasisTheory.net.Model;

Configuration config = new Configuration();
config.BasePath = "https://api.basistheory.com";
config.AddApiKey("BT-API-KEY", "YOUR_API_KEY");

var apiInstance = new TenantsApi(config);

Tenant result = apiInstance.Get();

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

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

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

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

using BasisTheory.net.Api;
using BasisTheory.net.Client;
using BasisTheory.net.Model;

Configuration config = new Configuration();
config.BasePath = "https://api.basistheory.com";
config.AddApiKey("BT-API-KEY", "YOUR_API_KEY");

var apiInstance = new TenantsApi(config);
var updateTenantRequest = new UpdateTenantRequest()
{
    Name = ...
    Settings = ...
};

Tenant result = apiInstance.Update(updateTenantRequest);

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"));
    }
}

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

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

Permissions

tenant:delete

Request

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

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

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

await bt.tenants.delete();

using BasisTheory.net.Api;
using BasisTheory.net.Client;
using BasisTheory.net.Model;

Configuration config = new Configuration();
config.BasePath = "https://api.basistheory.com";
config.AddApiKey("BT-API-KEY", "YOUR_API_KEY");

var apiInstance = new TenantsApi(config);

apiInstance.Delete();

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

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

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 "https://api.basistheory.com/tenants/self/reports/usage" \
  -H "BT-API-KEY: <MANAGEMENT_API_KEY>"

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

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

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

using BasisTheory.net.Api;
using BasisTheory.net.Client;
using BasisTheory.net.Model;

Configuration config = new Configuration();
config.BasePath = "https://api.basistheory.com";
config.AddApiKey("BT-API-KEY", "YOUR_API_KEY");

var apiInstance = new TenantsApi(config);

TenantUsageReport result = apiInstance.GetTenantUsageReport();

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

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

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

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

Get a Tenant​

Permissions​

Request​

Response​

Update Tenant​

Permissions​

Request​

Request Parameters​

Response​

Delete Tenant​

Permissions​

Request​

Response​

Get Tenant Usage Report​

Permissions​

Request​

Response​

Tenant Object​

Tenant Settings Object​

Tenant Usage Report Object​

Token Report Object​

Token Type Metrics Object​

Get a Tenant

Permissions

Request

Response

Update Tenant

Permissions

Request

Request Parameters

Response

Delete Tenant

Permissions

Request

Response

Get Tenant Usage Report

Permissions

Request

Response

Tenant Object

Tenant Settings Object

Tenant Usage Report Object

Token Report Object

Token Type Metrics Object