Token Intents

A Token Intent is a short-lived resource that simplifies the collection and validation of sensitive data from public applications. Token Intents serve as placeholders for sensitive data similarly to Tokens, and allow for additional validation to be performed (e.g. Credit Card Authentication, 3DS, Fraud Checks) before being converted into a Token for long-term retention.

A Token Intent automatically expires after 1 day. You may request a change to this default TTL (up to 48 hours) in your Tenant Quotas in the portal.

Create Token Intent

Create a new token intent.

POST

https://api.basistheory.com/token-intents

Permissions

token-intent:create

Request

cURL

curl "https://api.basistheory.com/token-intents" \
-H "BT-API-KEY: <API_KEY>" \
-H "Content-Type: application/json" \
-X "POST" \
-d '{
  "type": "card",
  "data": {
    "number": "4242424242424242",
    "expiration_month": 12,
    "expiration_year": 2025,
    "cvc": "123"
  }
}'

Node

await client.tokenIntents.create({
  type: "card",
  data: {
    number: '4242424242424242',
    expiration_month: 12,
    expiration_year: 2025,
    cvc: '123'
  },
});

JavaScript (legacy)

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

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

const tokenIntent = await bt.tokenIntents.create({
  type: "card",
  data: {
    number: '4242424242424242',
    expiration_month: 12,
    expiration_year: 2025,
    cvc: '123'
  },
});

C#

await client.TokenIntents.CreateAsync(new CreateTokenIntentRequest
{
  Type = "card",
  Data = new
  {
    number = "4242424242424242",
    expiration_month = 12,
    expiration_year = 2025,
    cvc = "123",
  }
});

Python

client.token_intents.create(
  type="card",
  data={
    "number": '4242424242424242',
    "expiration_month": 12,
    "expiration_year": 2025,
    "cvc": '123'
  }
)

Java

new TokenIntentsClient(ClientOptions.builder().build()).create(CreateTokenIntentRequest.builder()
    .type("card")
    .data(new HashMap<String, Object>() {{
        put("number", "4242424242424242");
        put("expiration_month", 12);
        put("expiration_year", 2025);
        put("cvc", "123");
    }})
    .build());

Go

tokenIntent, err := client.TokenIntents.Create(ctx, &basistheory.CreateTokenIntentRequest{
    Type: "card",
    Data: map[string]interface{}{
        "number": "4242424242424242",
        "expiration_month": 12,
        "expiration_year": 2025,
        "cvc": "123",
    },
})

Request Parameters

Attribute	Required	Type	Default	Description
type	true	string	null	The type of token intended to be created
data	false	any	null	The plaintext data to tokenize. Required when encrypted is not provided; must satisfy validation rules for the chosen token type
encrypted	false	string	null	A client-side encrypted JWE payload containing token intent data. Required when data is not provided. See Client Encryption Keys

Provide either data or encrypted, not both.

The type network_token is not available at this time.

Create Token Intent with Encrypted Data

You can create Token Intents using client-side encrypted payloads instead of sending plaintext data. First, create a Client Encryption Key from your backend, then use the returned public_key_pem and key_id to encrypt the same data you would otherwise send in data. Send the JWE compact serialization as encrypted.

If you are using Web Elements, you can use it to generate the encrypted payload instead of implementing JWE encryption yourself. See Encrypting Data with Web Elements, then send the returned .encrypted value as the Token Intent encrypted field.

Keep type in the Token Intent request body. The decrypted payload must contain the same data shape you would otherwise send in data. After decryption, normal token type validation applies.

Request

cURL

curl "https://api.basistheory.com/token-intents" \
-H "BT-API-KEY: <API_KEY>" \
-H "Content-Type: application/json" \
-X "POST" \
-d '{
  "type": "card",
  "encrypted": "<ENCRYPTED_PAYLOAD>"
}'

Node

await client.tokenIntents.create({
  type: "card",
  encrypted: "<ENCRYPTED_PAYLOAD>",
});

C#

await client.TokenIntents.CreateAsync(new CreateTokenIntentRequest
{
  Type = "card",
  Encrypted = "<ENCRYPTED_PAYLOAD>",
});

Python

client.token_intents.create(
  type="card",
  encrypted="<ENCRYPTED_PAYLOAD>",
)

Java

new TokenIntentsClient(ClientOptions.builder().build()).create(CreateTokenIntentRequest.builder()
    .type("card")
    .encrypted("<ENCRYPTED_PAYLOAD>")
    .build());

Go

encrypted := "<ENCRYPTED_PAYLOAD>"

tokenIntent, err := client.TokenIntents.Create(ctx, &basistheory.CreateTokenIntentRequest{
    Type: "card",
    Encrypted: &encrypted,
})

Response

Returns a 201 status code with a response body containing a Token Intent on success. Returns an error if there were validation errors, or the Token Intent failed to create.

Invalid encrypted payloads return a 400 response with the title Unable to decrypt token. Payloads encrypted with an unrecognized client encryption key return a 422 response with the title Unrecognized client encryption key.

{
  "id": "665bf471-d675-4165-9336-4fc9c1a73fad",
  "tenant_id": "8935ed5e-c082-4837-9063-6f0a2b4265dc",
  "type": "card",
  "card": {
    "bin": "42424242",
    "last4": "4242",
    "expiration_month": 12,
    "expiration_year": 2025,
    "brand": "visa",
    "funding": "credit",
    "product": {
      "code": "F"
    },
    "issuer_country": {
      "alpha2": "PL",
      "name": "Bermuda",
      "numeric": "369"
    },
    "authentication": "sca_required"
  },
  "fingerprint": "BzQfn8W5PTjHMZgmJfbTjNceWNTnqLEEoEEuhtS7fHca",
  "created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
  "created_at": "2020-09-15T15:53:00+00:00",
  "expires_at": "2024-10-30T19:23:57+00:00"
}

Get a Token Intent

Retrieves a Token Intent by its ID.

GET

https://api.basistheory.com/token-intents/{id}

Permissions

token-intent:read

Request

cURL

curl "https://api.basistheory.com/token-intents/665bf471-d675-4165-9336-4fc9c1a73fad" \
-H "BT-API-KEY: <API_KEY>"

Node

await client.tokenIntents.get("665bf471-d675-4165-9336-4fc9c1a73fad");

C#

await client.TokenIntents.GetByIdAsync("665bf471-d675-4165-9336-4fc9c1a73fad");

Python

client.token_intents.get(
  id="665bf471-d675-4165-9336-4fc9c1a73fad"
)

Java

new TokenIntentsClient(ClientOptions.builder().build()).get("665bf471-d675-4165-9336-4fc9c1a73fad");

Go

tokenIntent, err := client.TokenIntents.Get(ctx, "665bf471-d675-4165-9336-4fc9c1a73fad")

URI Parameters

Attribute	Required	Type	Default	Description
id	true	string	null	The ID of the token intent

Response

Returns a 200 status code with a response body containing a Token Intent on success. Returns an error if the Token Intent was not found or you don't have permission to access it.

{
  "id": "665bf471-d675-4165-9336-4fc9c1a73fad",
  "tenant_id": "8935ed5e-c082-4837-9063-6f0a2b4265dc",
  "type": "card",
  "card": {
    "bin": "42424242",
    "last4": "4242",
    "expiration_month": 12,
    "expiration_year": 2025,
    "brand": "visa",
    "funding": "credit",
    "product": {
      "code": "F"
    },
    "issuer_country": {
      "alpha2": "PL",
      "name": "Bermuda",
      "numeric": "369"
    },
    "authentication": "sca_required"
  },
  "fingerprint": "BzQfn8W5PTjHMZgmJfbTjNceWNTnqLEEoEEuhtS7fHca",
  "created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
  "created_at": "2020-09-15T15:53:00+00:00",
  "expires_at": "2024-10-30T19:23:57+00:00"
}

Delete Token Intent

Deletes a Token Intent without waiting for expiration. Use this endpoint to remove Token Intents that fail validation.

DELETE

https://api.basistheory.com/token-intents/{id}

Permissions

token-intent:delete

Request

cURL

curl "https://api.basistheory.com/token-intents/dda42a6b-964b-46d8-b315-eb6dfda37c32" \
-H "BT-API-KEY: <API_KEY>" \
-X "DELETE"

Node

await client.tokenIntents.delete("dda42a6b-964b-46d8-b315-eb6dfda37c32");

JavaScript (legacy)

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

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

await bt.tokenIntents.delete("dda42a6b-964b-46d8-b315-eb6dfda37c32");

C#

await client.TokenIntents.DeleteAsync("id");

Python

client.token_intents.delete(
  id="id",
)

Java

new TokenIntentsClient(ClientOptions.builder().build()).delete("dda42a6b-964b-46d8-b315-eb6dfda37c32");

Go

err := client.TokenIntents.Delete(ctx, "dda42a6b-964b-46d8-b315-eb6dfda37c32")

URI Parameters

Attribute	Required	Type	Default	Description
id	true	string	null	The ID of the token intent

Response

Returns a 204 status code and empty body on success. Returns an error if the Token Intent failed to delete.

Convert Token Intent to Token

To convert a Token Intent into a Token, you'll utilize the Create Token or Tokenize endpoint by passing in a token_intent_id instead of type and data. All other attributes of a token are available during the conversion.

Token Intents created with encrypted are converted the same way.

Conversion Rules

Card

Attribute	Rule
cvc	The CVC will not be moved to the Token, as the Card has been authorized. Ensure all actions have been completed with the CVC before conversion.

Deduplication

If token deduplication is enabled, and a Token exists in your Tenant with the same fingerprint and container as the converted token, then the existing Token will be updated. This update operation follows the same merge-patch behaviors that are used when updating a Token.

Token Intent Object

Attribute	Type	Description
id	string	Unique identifier of the Token Intent, which can be used in detokenization expressions or to convert to a token
tenant_id	uuid	The Tenant ID which owns the Token Intent
type	string	The type of token intended to be created
card	object	The Card Details when type is card or card_number, otherwise null.
bank	object	The Bank Details when type is bank, otherwise null.
network_token	object	The Card Details when type is network_token, otherwise null.
authentication	object	The 3DS authentication information (ie: cryptogram) when type is network_token, otherwise null.
fingerprint	string	Uniquely identifies the contents of this Token Intent using the default fingerprint expression for the Token Types
expires_at	string	The expiration date for this Token Intent
created_by	uuid	The Application ID which created the Token Intent
created_at	date	Created date of the Token Intent in ISO 8601 format
_extras	object	(Response-Only) An object containing information regarding the tokenization process

Extras Object

Attribute	Type	Description
network_token_ids	array	A list of network token IDs that were created based on the current token intent

Card Details

Attribute	Type	Nullable	Description
bin	string	No	Six to eight digit BIN of the card
last4	string	No	Last four digits of the card
expiration_month	number	No	The 2-digit expiration month of the card
expiration_year	number	No	The 4-digit expiration year of the card
brand	string	Yes	The primary card brand
funding	string	Yes	The primary funding type of the card
segment	string	Yes	The segmentation of the card (eg., Consumer, Commercial)
product	object	Yes	Describes the card product. See Product for details
issuer	object	Yes	Describes the country and issuing bank. See Issuer for details
issuer_country	object	Yes	Describes the issuing country. See Issuer Country for details
authentication	string	Yes	The authentication type required for this card
additional	array	Yes	Other records found for the same BIN. Each entry has the same shape as the primary record. See Card Additional below for details.

Card properties show the primary card details for the BIN. When more than one record matches the BIN, the extra records land in additional[] — most often co-badged secondary networks (e.g., STAR, PULSE, NYCE) on a primary brand, but also alternate issuers or funding types when a BIN spans them. When the primary brand, funding, issuer, or authentication doesn't match the card you're handling, check additional[] for a record that does. Entries are unordered; match by field values, not by index.

If a card number does not correspond to any supported card brand or known BIN Details, then brand, funding, segment, product, issuer, issuer_country, and authentication will default to null and the default BIN will be returned.

Card Additional

Attribute	Type	Description
brand	string	An additional card brand
funding	string	An additional funding type of the card
authentication	string	An additional authentication type required for this card
issuer	object	Describes the country and issuing bank. See Issuer for details

Authentication Types

Authentication Type	Description
sca_required	Indicates that Strong Customer Authentication (SCA) is required (e.g. 3DS)

Card Brands

The following card brands are supported in the card property (primary details). Please note that the additional property may contain extra card brands not listed in this table.

Brand	Description
american-express	American Express
diners-club	Diners Club
discover	Discover
ebt	EBT
elo	Elo
hipercard	Hipercard
jcb	JCB
mastercard	Mastercard
mir	MIR
private-label	Private Label
proprietary	Proprietary
unionpay	UnionPay
visa	Visa

Card Funding Types

Funding Type	Description
credit	Credit Card
debit	Debit Card
prepaid	Prepaid Card

Issuer

Attribute	Type	Description
country	string	Issuing country ISO3166 alpha country code
name	string	Issuing bank name

Issuer Country

Attribute	Type	Description
alpha2	string	Issuing country ISO3166 alpha country code
numeric	string	Issuing country ISO3166 numeric country code
name	string	Issuing country name

Product

The card product identifies the specific product within a brand and funding type — for example, distinguishing Visa Classic from Visa Signature or Visa Infinite. These values are derived from BIN Details enrichment, so they share its coverage and accuracy.

Attribute	Type	Description
code	string	The card product code assigned by the issuing network. See the Product Code Reference for the full list of Visa and Mastercard codes. null when the network does not provide one.

Bank Details

Attribute	Type	Description
routing_number	string	The routing number of the bank account
account_number_last4	string	Last four digits of the bank account number