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.
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, but you're allowed to create as many Tenants as you'd like within Basis Theory. You can use multiple Tenants to isolate different domains of data, and to support your Software Development Life Cycle (SDLC).
The user account that was used to create a Tenant in the Portal will be designated as the 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 Business Unit
Many large enterprise and corporate organizations have multiple business units or properties which have different data needs. Some business units may not want other parts of the organization to have direct access to data they own and manage. Creating a Tenant for each business unit enables your organization to isolate and limit access to their data by issuing an Application with limited access controls to other units within the organization.
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:
A short description of the Application describing its intended use, for example "Acme Billing App" or "Acme Mobile App".
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.
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.
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:
This behavior can be customized by defining 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.
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
API Keys should be regarded as highly sensitive, and should be stored a secret within in your environments.
ISO8601 compatible DateTime at which the application will be deleted.
To help you get started quickly, we provide a set of Application Templates for many common use cases,
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?
Sessions can help you achieve improved security by limiting the access granted to a public application and its API key. Since public API keys are used within frontend applications, they can potentially be accessed by untrusted parties who inspect or decompile your web or mobile application source code, or by inspecting network traffic in their browser or device. Because of these risks, Basis Theory only allows public applications to be granted permission to create or update tokens to support collecting data, and never to read or use tokens.
However, even granting access to create or update tokens introduces risk, as unauthorized third parties could potentially gain access to your public API key and perform malicious actions:
- Tokens could be created within your tenant by unauthorized third parties, increasing your MAT count and potentially incurring charges
- If a token ID were exposed or guessed, that token could be updated by an unauthorized actor without your consent
Using sessions within a public application fully 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.
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:
A short description of the rule to help you identify its purpose.
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
token:read permission on the
/pci/ Container will allow that Application the ability to
read Tokens in the
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
and another rule with lower priority grants
token:read permission on the
/pci/ Container with a
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 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
equals and value
allow the application to only access the token with the given
Conditions are mutually exclusive with Container and are currently only available for Sessions.
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.
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
dataproperty from Tokens
mask- returns masked
maskexpression is defined on the Token, otherwise
reveal- returns the original plaintext
Be cautious whenever applying a
reveal transform. This is especially true when granting the
token:search permissions, as this will allow your Application to read plaintext data. This may result in your systems being pulled into compliance scope.
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,
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