Access Controls

Basis Theory secures sensitive data as Tokens that are stored within an isolated compliant environment, called a Tenant. Your systems interact with Tokens or Services (e.g., Proxy, Reactors) through the Basis Theory API using an API key that is issued to an Application. Access to your Tenant's data is limited by applying access controls to an Application via Permissions and Access Rules to ensure services and users only have access to the data they need.

Basis Theory Account

It is strongly recommended to register for a Basis Theory Account using your work email address. This practice enhances accountability and aligns with security best practices for online platform access.

Basis Theory supports Single Sign-On (SSO) for simplified access management. If you are interested in using it, please reach out to us.

Basis Theory accounts are usually created after one of the following patterns:

• 🧑‍💻 Personal Accounts (e.g., john.doe@yourcompany.com) are used in local development situations such as learning, testing, contributing, POC, etc.
• 🏢 Managed Accounts (e.g., payments@yourcompany.com, platform@yourcompany.com) are team or company-owned service accounts used to manage environments, such as Shared Development, Staging and Production.

See below an example of an optimal Account and Tenant setup for a cross-region deployment:

Protecting the Basis Theory Account is entirely the user's responsibility. Make sure to:

• Turn on Two-Factor Authentication (2FA)
• Use a Password or Secret Manager to generate and store passwords securely
• Follow internal policies for Managed Accounts defined by your security team

What are Tenants?

Everything starts with a Tenant in your Basis Theory account. Tenants represent an isolated environment in which your Tokens and other resources are defined, managed, and stored. Data is not shared between Tenants.

There are two types of Tenants:

1. 🛠️ TEST Tenants are used for non-production use cases, and should only be used to store synthetic data. Test Tenants are not PCI compliant and must not contain real or live consumer data.
2. 🚀 PRODUCTION Tenants are used for storing real-world sensitive data and are fully compliant environments.

TEST and PRODUCTION Tenants run in separate dedicated environments with isolated infrastructure resources. This ensures your testing activities (load testing, integration testing, development) never impact production workloads. Learn more about Test Tenant environment changes.

Currently available deployment locations for Production Tenants are:

• 🇺🇸 United States
• 🇪🇺 Europe (GDPR compliant)
• 🇮🇳 India (DPDPA compliant)

Need to deploy a Production Tenant to a different region? Please reach out to us if you're interested in a region not listed above.

The user account used to create a Tenant in the Portal is the designated Tenant Owner. New members can be invited to an existing Tenant through the Members tab. Managing Tenant Members can also be done directly through the API.

Common Use Cases for Tenants

Enabling Your Software Development Life Cycle

Companies producing software typically create separate and identical environments to support their development and release processes. For example, developers and teams create Production environments to house their actual customer data and multiple non-Production environments to enable quick development and testing of their applications without impacting their Production systems. Basis Theory allows you to create these logical separations of data by creating a new Tenant for each environment:

Separating Data by Region

In some cases, large enterprises may use additional Production tenants for specific regional or highly regulated workloads. When considering extra Production tenants, prefer region‑based separation over mapping tenants directly to teams or business units.

Using a single, region-unified set of TEST tenants is a common and successful pattern.

What are Applications?

An Application represents an external software system or service that will be integrated with the Basis Theory API. Basis Theory's Applications are not coupled to a specific implementation type or technology. Applications could be a native app on a mobile device, a single-page application in a browser, or a backend service that executes on a server or in a serverless environment.

Applications within Basis Theory have the following properties and characteristics:

Name

A short description of the Application describing its intended use, for example "Acme Billing App" or "Acme Mobile App".

Application Type

• Private: Used by a backend system or service that runs primarily on a server or in a serverless environment (e.g., NodeJs, .NET, Java, or Ruby). Private Applications allow the broadest access to Token data as the API Key is expected to be kept private and secured within your systems.

• Public: Used for Browser, Mobile, or Desktop applications running natively on a device (e.g., iOS, Android, Windows, etc) where the application is collecting data for tokenization via an API call or using Basis Theory Elements. Public Applications have limited permissions available to ensure the API Key can be safely used within publicly available code.

• Management: Used with scripts or the Basis Theory Terraform Provider to manage your Tenant's settings and services (Applications, Reactors, Proxy, etc) without logging into our Portal.

There are some inherent risks associated with embedding a public API key within a public-facing frontend application. Take the time to understand these risks and consider using sessions within your frontend applications to mitigate these risks.

Access Controls

An Application is granted access to your Tenant's resources in one of two ways: by granting the Application a set of Permissions, or for more advanced scenarios, by defining one or more Access Rules.

Permissions

For basic authorization scenarios, an Application can simply be granted one or more permissions. Each Application Type allows a different set of permissions, and you can find a detailed list of them here.

Token permissions granted to Private or Public applications are applied to all Tokens (i.e. they are not scoped to a particular Container of Tokens). In order to ensure sensitive data is not inadvertently revealed by an Application, an implicit transform is applied for each operation:

Permission	Transform
token:create	mask
token:update	mask
token:read	mask
token:search	mask
token:use	reveal
token:delete	N/A

This behavior can be customized by defining Access Rules.

Access Rules

For more advanced authorization scenarios, Access Rules enable scoping a set of permissions to a subset of Tokens, and to customize the behavior when returning Token data from the API. Please see the section on What are Access Rules below for more details.

API Key

Your Application's API Key is used to authenticate your systems to the Basis Theory platform. The API Key can be used to make authenticated requests to our API directly, using Hosted Elements, or using the Basis Theory SDK. These API Keys follow a format similar to key_<region>_<type>_4qUtg83907AnDem90aJSzcN. API Keys should be regarded as highly sensitive, and should be stored a secret within in your environments.

Expires At

ISO8601 compatible DateTime at which the application will be deleted.

Application Templates

To help you get started quickly, we provide a set of Application Templates for many common use cases, such as Payments, Banking, and PII Data. The available application templates are presented after clicking on the "Create Application" button in the Portal.

If you are just getting started with Basis Theory, the Full Access template can be useful for testing and prototyping. This template will create a test Application that has been granted all permissions for interacting with Tokens within your Tenant. It is important to remember that the Full Access template should not be used for production Applications, and you should always strive to follow the principle of least privilege.

Selecting a template will only pre-fill the Create Application form, and any settings or access rules within the Application can be customized. Once created, your Application will have no relationship with the template and can be updated independently.

If you have a particular use case that is not covered by one of the existing templates, you can also create a custom Application to satisfy your specific requirements by choosing the Create Your Own option.

Common Use Cases for Applications

Grant Multiple Systems Access Following the Principle of Least Privilege

A common use-case for Applications is to grant minimal access to multiple systems where each system is only authorized to perform necessary operations and access a relevant subset of data within a Tenant. This could mean that one system is only allowed to collect Tokenized data, another system is allowed to read the data to perform analytics, and a third system is only allowed to Proxy the data to an integrated 3rd party but never access the raw data.

Enable partners to use data secured by Basis Theory

Often, businesses need to grant their partners access to their sensitive data — traditionally, these businesses would just export the needed data and send it to their partner. With Basis Theory Applications, a business can create an Application that is restricted to ONLY the data that partner needs. In some cases, businesses will not allow their partners direct access to the raw data, but rather only allow them to Proxy the data to another API or execute serverless workloads on the sensitive data using Reactors.

Manage Basis Theory Assets with Infrastructure as Code

The Management application type allows the Basis Theory platform to be configured entirely via our API. This enables engineers to write scripts or to use IaC (Infrastructure as Code) tooling such as Terraform to manage your Tenants and Services without logging into our Portal UI.

What are Sessions?

Sessions provide an alternative mechanism to grant temporary elevated access to your public applications.

Generally speaking, sessions are created by and issued to a public application (within your frontend) and authorized by a private application (within your backend). Sessions can be authorized to only access specific tokens or containers, and to perform a limited set of operations on those tokens. You can learn more about how to create and authorize sessions in the guide Access Data Using Sessions or continue reading below to learn more about when to consider using sessions.

Why Use Sessions?

Most user-facing applications such as checkout pages, mobile apps, etc. integrate with Basis Theory using Public Application Keys. They are simple to create and use, yet have very narrow permissions available. You can only use such keys to interact with Basis Theory API in order to create and update tokens. This intentional design prevents unauthorized disclosure of sensitive information. For instance, if a malicious actor gets hold of the Public Key by reverse engineering your code or inspecting application network traffic, their actions are confined by the application's permissions. This limitation ensures they cannot read or use any tokenized data.

However, there are still some residual risks with such practice. Leaked Public Application keys could still be used to:

• Create tokens within your Tenant by unauthorized third parties.
• Update existing tokens, if a token ID were exposed or guessed - as long as the Public Application has token:update permission. Grant token:update to Public Applications only when strictly necessary.

Using sessions within a Public Application mitigates these risks and offers the following benefits over a Public API key-only approach:

• Prevent Anonymous Use: Since sessions are authorized by a private application in a backend service that you own, you are able to authenticate all requests for a session.
• User-Specific Access Controls: You can apply your own custom authorization logic to limit access to only the tokens that should be accessible by each user.
• Ability to Read or Use Tokens: Sessions can be authorized to perform any token operation, not only creating or updating tokens.
• Limited Lifetime: Sessions are created just-in-time and are intended to be short-lived - by default, sessions expire after 3 minutes.

Public Application Keys are geared toward integration simplicity, while Sessions provide broader functionality range and more granular access controls.

Use Cases for Sessions

Sessions enable you to fully mitigate many of the risks associated with exposing public API keys, while also enabling use cases beyond collecting data within your frontend applications.

Sessions are a good fit for the following use cases:

• Revealing tokens in a front end application in plaintext (see reveal sensitive data with Elements)
• Calling the proxy or reactors from your frontend application
• Restricting the access granted to public API keys to prevent unauthorized use
  • Only allow tokens to be created by authenticated users in your system
  • Only allow tokens to be updated by authenticated and authorized users in your system

What are Access Rules?

Access Rules are the building blocks for constructing fine-grained access control policies for an Application. When performing an operation through the Basis Theory API, Access Rules are evaluated in priority order until the first rule is found with matching container or conditions. Once a matching rule is identified, the transform defined on the rule determines if and how Token data will be returned from the API. If no matching rules are found, access to the requested resource is denied with a 403 Forbidden error.

Access Rules are currently only supported on Private and Public Application types, and only control access to Token resources. Access Rules are not supported on Management Applications at this time.

Access Rules are comprised of the following properties:

Description

A short description of the rule to help you identify its purpose.

Container

Access Rules can be scoped to a specific set of Tokens using Containers. Containers are a Token attribute that enable you to logically organize Tokens into hierarchical paths, similar to a UNIX directory structure.

Permissions granted on a Container are inherited on all sub-Containers. For example, having an Access Rule granting token:read permission on the /pci/ Container will allow that Application the ability to read Tokens in the /pci/low/ and /pci/high/ Containers.

To specify different access controls on a sub-Container, you may apply another rule with higher priority that is scoped to the sub-Container. For example, given a rule that grants token:read permission on the /pci/high/ Container with a mask transform and another rule with lower priority grants token:read permission on the /pci/ Container with a reveal transform, then reading tokens in the /pci/high/ container will return masked data, and reading tokens in the /pci/low/ container will return plaintext data.

Conditions

Conditions allow specifying more specific restrictions for the access rule to be matched, such as scoping them to a specific token. For example, having a condition with attribute id, operator equals and value <tokenId>, will allow the application to only access the token with the given <tokenId> ID.

Conditions are mutually exclusive with Container and are currently only available for Sessions.

Permissions

One or more permissions to be granted on Tokens in the specified Container. Check out our API docs for a detailed list of supported permissions by Application type.

Transform

Transforms are applied to the data property of a Token within API responses, allowing you to specify which view of the data is appropriate to expose to the Application. The following transforms are supported:

• redact - redacts the data property from Tokens
• mask - returns masked data if a mask expression is defined on the Token, otherwise data is redacted
• reveal - returns the original plaintext data

Be cautious whenever applying a reveal transform. This is especially true when granting the token:read or token:search permissions, as this will allow your Application to read plaintext data. This may result in your systems being pulled into compliance scope.

Priority

Each access rule is assigned a unique priority value, which specifies the order in which the rules will be evaluated. Rules are evaluated in ascending priority order, with the lowest numerical value having the highest precedence.

Common Use Cases for Access Rules

Grant Access to a Single Data Classification

Access Rules can be scoped to a specific data classification of Tokens. To enable this use case, first ensure your Tokens are organized into classification-based Containers, for example /pci/, /pii/, and /general/.

Grant Access to a Single Customer's Data

Your customers' sensitive data can be partitioned within Basis Theory, for example, to enable you to offer your customers single-tenant environments that only have access to a single customer's data. To enable this use case, first ensure your Tokens are organized into Containers by customer, for example /customer-1/, /customer-2/, etc.