Understanding Classifications, Impact Levels, and Permissions
Every Application you create has a unique set of permissions that control what operations you can perform with that Application’s API Key. Token Permissions are configured based on the operation, the Token Classification, and the Token Impact Level. Let’s explore how these three things come together with Permissions to give you control over Token access.
Impact Levels
Basis Theory defines its Impact Levels using the standard NIST-defined low
, moderate
, and high
. Impact Levels provide a framework for understanding the potential harm of a security breach. Low
is for data that poses the least risk, where the impact would be limited if the data were leaked; examples include the expiration date for a credit card, the routing number for a bank, or the state someone lives in. Moderate
is for data that would have a serious impact to the organization or user; examples include phone numbers and zip codes. High
is for data that would have a severe or catastrophic impact to the organization or user; examples include social security numbers, driver’s license numbers, and account numbers.
All Token Types have a default Impact Level. When creating a token of any type you are able to change the default Impact Level, as long as it doesn’t go lower than the minimum level defined for that Token Type. For example, employer_id_number
’s have a default Impact Level of high
but can be set to low
; card_number
Tokens, however, must always have a high
Impact Level.
curl "https://api.basistheory.com/tokens" \
-H "BT-API-KEY: <BT_API_KEY>" \
-H "Content-Type: application/json" \
-X "POST" \
-d '{
"type": "token",
"data": "Sensitive Value",
"privacy": {
"impact_level": "moderate"
}
}'
Classifications
Token Classifications define the type of data inside the Token. Basis Theory supports four different Classifications:
bank
indicates that the Token contains data that falls under banking compliance, such as Nacha.pci
indicates that the Token contains data that requires PCI compliance.pii
indicates that the Token contains Personally Identifiable Information.general
is for all Tokens that don’t need a more specific classification or compliance requirement.
Need a different classification? Contact us!
As with the Impact Levels, each Token Type has a default Classification which can be overridden as long as it doesn’t become less specific than the default Classification. You cannot “downgrade” a Token from pci
to general
.
curl "https://api.basistheory.com/tokens" \
-H "BT-API-KEY: <BT_API_KEY>" \
-H "Content-Type: application/json" \
-X "POST" \
-d '{
"type": "token",
"data": "Sensitive Value",
"privacy": {
"classification": "pii"
}
}'
Restriction Policies
In addition to the Impact Level and Classification, Tokens can have a Restriction Policy set. Basis Theory supports two policies: mask
and redact
. When the Token is read by an Application with permission to read only lower Impact Levels than the Token, the Restriction Policy defines whether the Token’s data should be masked or redacted. For example, the social_security_number
Token Type has a default Restriction Policy of mask
and a default Impact Level of high
. If an Application that only has permission to read low
Impact Level Tokens attempts to read a social security number, the data will be returned masked:
curl "https://api.basistheory.com/tokens" \
-H "BT-API-KEY: <BT_API_KEY>" \
-H "Content-Type: application/json" \
-X "POST" \
-d '{
"type": "social_security_number",
"data": "123-45-6789"
}'
curl "https://api.basistheory.com/tokens/<TOKEN_ID>" \
-H "BT-API-KEY: <BT_API_KEY>" \
-H "Content-Type: application/json" \
-X "GET"
{
"id": "8deb3363-288a-49b2-8c5f-e6b598a8afff",
"type": "social_security_number",
"data": "XXX-XX-6789",
"privacy": {
"classification": "pii",
"impact_level": "high",
"restriction_policy": "mask"
},
"tenant_id": "c28392d1-15ec-479a-ac15-bbe2764ad66d",
"created_by": "b848d641-71fb-439d-808a-efbb8237c282",
"created_at": "2022-04-20T23:12:10.401Z"
}
Permissions
Each Application Type has its own set of permissions to choose from (view the full list here). Client-side
and Elements
Applications are only able to create
Tokens, ensuring that you are able to safely use the Application Key in your client-side code without worrying about a malicious actor using that key to decrypt your data. Management
Applications can manage infrastructure items only, such as Tenants and Applications, and they cannot interact with Tokens; all other Application Types are restricted to data operations with Tokens. Token permissions come in the format token:<classification>:<operation>:<scope?>
, for instance token:bank:read:low
or token:pci:use:proxy
.
Token Permissions control three things:
- What Classification of Tokens the Application has access to interact with
- What operations the Application can use (create, delete, use, etc.)
- How the detokenized plain text data is returned when reading a Token
The <classification>
segment of the permission tells you what Classification of Token the Application can interact with. If an Application is only granted the token:pii:create
permission, it cannot create a Token with the Classification pci
or bank
.
Which operations an Application can use is likewise controlled by the permissions. If an Application has the token:pii:delete
permission only, it cannot create any Tokens, only delete Tokens with the Classification of pii
. use
is an additional operation to the standard CRUD operations that allows an Application to detokenize Tokens of that classification within the Proxy or Reactors (*:use:proxy
or *:use:reactor
respectively).
The last consideration when determining what permissions to grant an Application is the Impact Level. Applications can only read
the plain text value of Tokens that have the same or lower Impact Level than the permission. For instance, if an Application has the token:pii:read:high
permission, it can read all Tokens classified as pii
regardless of their Impact Level. However, if the Application only has token:pii:read:low
, the only Tokens it can fully detokenize are those with the low
Impact Level. If the Application tries to read a Token with a higher Impact Level (in this example, moderate
or high
), the data will be returned either masked or redacted, depending on the Restriction Policy assigned to the Token.