--- name: bt-tokens description: Model token schemas, masks, fingerprints, and opaque references. license: MIT metadata: tier: standard last_verified: '2026-09-25' --- # Tokens: schema and opaque references This is an overlay skill. It supplies token-shape guidance; load the feature skill that owns the workflow too. ## Canonical docs - Tokens: https://developers.basistheory.com/docs/concepts/what-are-tokens - Token API and token types: https://developers.basistheory.com/docs/api/tokens/ - Token intents: https://developers.basistheory.com/docs/concepts/token-intents - Search: https://developers.basistheory.com/docs/api/tokens/search - Detokenize: https://developers.basistheory.com/docs/api/tokens/detokenize - Expressions: https://developers.basistheory.com/docs/expressions/ **Answer requirement:** include at least one of the canonical developer-doc URLs above in every token-design explanation or review. Link the specific concept or API page, not the docs root alone, and do not substitute a marketing, changelog, or third-party mirror URL (for example a Postman collection) for the canonical product source. ## Guidance - Decide the token type and schema before writing adapter code. The schema should describe the sensitive object; the product code should store a typed opaque reference to it. - Keep masks and fingerprints as display/search aids, not substitutes for authorization to reveal data. - Token intents are for collect-now-decide-later flows and ephemeral collection handoff; do not treat them as durable stored-card tokens until converted. - Token Intent reads can be masked (`token-intent:read`) or plaintext (`token-intent:reveal`). Plaintext reveal can include cardholder data and CVC while the intent is active; require explicit permission, the `reveal` transform on matching access rules, and PCI scope awareness before recommending it. - `network_token` is a supported token and token intent type for a DPAN you already hold: `data.number` (13–19 digits, Luhn-valid; a raw PAN is rejected), `data.expiration_month`, `data.expiration_year`, `authentication.threeds_cryptogram` (required, redacted on read), `authentication.eci_indicator` (optional). It needs `network-token:create` alongside the create permission, and 3DS sessions do not consume the cryptogram (https://developers.basistheory.com/docs/api/tokens/#create-a-network-token, https://developers.basistheory.com/docs/api/tokens/token-intents#create-a-network-token-intent). Provisioning a network token from a card is `bt-network-tokens`. - `owner_merchant_id` on create assigns the token to a tenant merchant and defaults to the `BT-MERCHANT-ID` header merchant; ownership is not retroactive, so decide it at creation (https://developers.basistheory.com/docs/concepts/what-are-tenant-merchants#merchant-context-acting-as-a-merchant). - Additional card brands (co-badge, e.g. `cartes-bancaires`) are returned in the token's `card.additional` array, each entry carrying `brand`; the old `additional_card_brands` enrichment object is gone (https://developers.basistheory.com/docs/api/tokens/#card-additional). - Do not grant `token:update` to a Public Application unless strictly necessary: an exposed browser key could then modify any token whose ID is known. Use a backend Private key, Sessions, or Token Intents instead (https://developers.basistheory.com/docs/concepts/access-controls). - Expression strings belong in controlled proxy/reactor templates, not user-controlled token reference fields. - For framework integrations, validate all token-shaped fields before persistence and transport using [../\_shared/references/credential-boundary.md](../_shared/references/credential-boundary.md). - In reviews and plans, enumerate every credential-bearing variant and its load-bearing field names exactly as they appear in the repository. Do not collapse `proxy_card.vault_data_card.card_number`, `vault_card_token_data.card_cvc`, or equivalent framework variants into a generic "card source." ## Review output requirements - State the persistence boundary explicitly: **reject PAN-shaped and CVC-shaped values before persistence**, including values hidden in token-shaped variants. - State the expression boundary explicitly: **reject control characters and expression metacharacters before proxy template construction**. Do not merely say that inputs should be validated. ## When to load other skills - Collection surface: `bt-collect`. - Payment source type or CVC recollection: `bt-payments`. - Masked display, reveal, search, or PII governance: `bt-pii`. - Proxy expression transport: `bt-proxy`. - Migration or portability: `bt-migrate`. ## Basis Theory implementation guidance When the answer needs implementation judgment beyond public docs, load only the relevant slices below from [../\_shared/references/implementation-guidance/README.md](../_shared/references/implementation-guidance/README.md). Treat these as implementation patterns, not canonical product behavior; keep public docs as the source of truth and label the guidance as **Implementation pattern** or **Assumption** unless docs prove it. - `../_shared/references/implementation-guidance/tokens/` - `../_shared/references/implementation-guidance/token-intents/` ## Working conventions (shared by all Basis Theory skills) - Public Basis Theory docs are the source of truth for product behavior. Link the specific docs page behind any product claim; if a skill and the docs disagree, follow the docs. - Keep customer ownership clear: customers own PSP accounts, credentials, compliance decisions, production rollout, and application code. Skills can guide plans, bounded changes, and examples; they do not certify production readiness. - Never request, echo, store, or commit real credentials. Use placeholders such as `` and prefer sandbox or synthetic data for examples. - If a live-looking credential, live cardholder data, or production secret appears, stop mutation work, tell the user exactly where it appeared, and require rotation/revocation before continuing. - Default to test tenants and PSP sandboxes. Do not run or recommend production charges, refunds, card reveals, credential migrations, or data moves unless the user explicitly asks and the plan names safeguards, rollback, and customer approval. - Treat vague planning, audit, review, and “should we” prompts as read-only unless the user explicitly asks for a bounded implementation change. - Before changing product code, map the existing checkout/data flow, credential-bearing paths, persistence, retries, refunds, webhooks, logs, and rollback expectations. - End with an honest final report: done, assumed, remaining, proof run, unverified live behavior, rollback, and go-live items.