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

JavaScript

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

const bt = await new BasisTheory().init("key_N88mVGsp3sCXkykyN2EFED");

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

C#

using BasisTheory.net.Tenants;

var client = new TenantClient("key_N88mVGsp3sCXkykyN2EFED");

var tenant = await client.GetSelfAsync();

Python

import basistheory
from basistheory.api import tenants_api

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="key_N88mVGsp3sCXkykyN2EFED")) 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: "key_N88mVGsp3sCXkykyN2EFED"},
  })

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

Response

Returns a Tenants 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": {
    "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: key_N88mVGsp3sCXkykyN2EFED" \
  -H "Content-Type: application/json" \
  -X "PUT" \
  -d '{
    "name": "My Example Tenant",
    "settings": {
      "deduplicate_tokens": "true"
    }
  }'

JavaScript

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

const bt = await new BasisTheory().init("key_N88mVGsp3sCXkykyN2EFED");

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

C#

using BasisTheory.net.Tenants;

var client = new TenantClient("key_N88mVGsp3sCXkykyN2EFED");

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

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

  updateTenantRequest := *basistheory.NewUpdateTenantRequest("My Example Tenant")
  updateTenantRequest.SetSettings(map[string]string{
    "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": {
    "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: key_N88mVGsp3sCXkykyN2EFED" \
  -X "DELETE"

JavaScript

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

const bt = await new BasisTheory().init("key_N88mVGsp3sCXkykyN2EFED");

await bt.tenants.delete();

C#

using BasisTheory.net.Tenants;

var client = new TenantClient("key_N88mVGsp3sCXkykyN2EFED");

await client.DeleteAsync();

Python

import basistheory
from basistheory.api import tenants_api

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="key_CxEaZMmFu3UAcuNcCbvBVu")) 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: "key_N88mVGsp3sCXkykyN2EFED"},
  })

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

JavaScript

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

const bt = await new BasisTheory().init("key_N88mVGsp3sCXkykyN2EFED");

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

C#

using BasisTheory.net.Tenants;

var client = new TenantClient("key_N88mVGsp3sCXkykyN2EFED");

var tenantUsageReport = await client.GetTenantUsageReportAsync();

Python

import basistheory
from basistheory.api import tenants_api

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="key_N88mVGsp3sCXkykyN2EFED")) 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: "key_N88mVGsp3sCXkykyN2EFED"},
  })

  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 setting 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
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 Monthly Active Tokens (MATs), check out our guide.

Token Type Metrics Object

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