> ## Documentation Index > Fetch the complete documentation index at: https://docs.knoxcall.com/llms.txt > Use this file to discover all available pages before exploring further. # Vaults overview > Tokenize sensitive values (PCI cards, SSNs, emails, any PII) so your databases store opaque tokens instead of raw data. KnoxCall holds the values behind a per-vault encryption key. # Vaults overview KnoxCall's **Vaults** feature is a **data tokenization service**. You exchange a sensitive value (a credit card number, an SSN, an email, an arbitrary blob) for a **token** — a shorter, opaque string. Your databases and analytics pipelines store the token. Whenever you need the original value, you call KnoxCall's detokenize endpoint. The Vault parallel: this is what HashiCorp calls a *Tokenization Engine*. The competitor parallel: Basis Theory and Skyflow. Use it for: * **PCI scope reduction** — store tokens that pass card-shape validation in your DB. KnoxCall holds the real PANs in scope. * **PII lifecycle controls** — set TTLs so emails / SSNs auto-expire; cryptographic erasure when a customer requests deletion. * **Format preservation** — tokens that pass the same format checks as the originals (e.g. Luhn-valid for cards, NNN-NN-NNNN for SSNs), so existing systems keep working without schema changes. * **Centralised audit** — every detokenize lands in the audit log with the user/key that read it. ## Why use it | Problem | Without KnoxCall | With KnoxCall | | ------------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------ | | PAN scattered across 14 microservices | Every service is in PCI scope | Only the gateway sees PANs; everything downstream sees tokens | | Customer asks for deletion under GDPR | Hunt every DB + backup | Delete the vault key version → cryptographic erasure | | Email leak from analytics warehouse | Real emails leak | Tokenized emails leak — domain still useful for routing/cohorts | | Format-preserving = build it yourself | Hand-rolled FPE = subtle bugs | Built-in `pan` (Luhn-valid), `ssn` (9XX prefix avoids real SSNs), `email`, `generic` | ## How it works 1. **Create a vault** with a chosen [token format](#token-formats). The format is locked at creation — changing it later would invalidate every existing token. 2. **Tokenize** values: `POST /v1/vaults/{name}/tokens` with `{ value, metadata?, ttl_seconds? }`. KnoxCall returns a token string + an internal id. Store the token in your DB. 3. **Detokenize** when you need the original: `GET /v1/vaults/{name}/tokens/{token}`. Audited every time. 4. **Rotate** the vault's encryption key when you want to bump versions. Existing tokens still decrypt under their original version; new tokens encrypt under the new version. No re-encryption of stored data needed. 5. **Destroy** a vault to cryptographically shred every token in it. Permanently unreadable. ## Quick start (UI) 1. Go to **Protect → Vaults** in the admin UI and click **New Vault**. 2. Pick a **token format**: * `generic` — opaque token, safe for any value type. Default. * `pan` — credit card numbers (16 digits, Luhn-valid, BIN + last4 preserved). * `ssn` — US SSNs (9XX-XX-XXXX, last 4 preserved). * `email` — local-part tokenised, domain preserved. 3. Optional: set a **default TTL** so tokens auto-expire. 4. Save. Use the **Playground** tab to tokenize / detokenize a few values. ## Quick start (API) All responses use the standard `{ data: ..., meta: { request_id: "..." } }` envelope. The examples below show the `data` fields. ```bash theme={"dark"} # 1. Create a vault for credit card numbers curl -X POST https://api.knoxcall.com/v1/vaults \ -H "Authorization: Bearer $KC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "cards", "token_format": "pan" }' # 2. Tokenize a card curl -X POST https://api.knoxcall.com/v1/vaults/cards/tokens \ -H "Authorization: Bearer $KC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "value": "4111111111111111" }' # → data: { "id": "3f1c8e2a-9b7d-4c6a-8e21-0d5f4a1b2c3d", "token": "4111110000091111", "expires_at": null, "created_at": "2026-01-20T10:00:00.000Z" } # ^^^^^^ ^^^^ # BIN preserved last4 preserved # 3. Detokenize (audited) curl https://api.knoxcall.com/v1/vaults/cards/tokens/4111110000091111 \ -H "Authorization: Bearer $KC_API_KEY" # → data: { "id": "3f1c8e2a-9b7d-4c6a-8e21-0d5f4a1b2c3d", "token": "4111110000091111", "value": "4111111111111111", # "value_b64": "NDExMTExMTExMTExMTExMQ==", "metadata": null, # "expires_at": null, "created_at": "...", "crypto_key_version": 1 } ``` ## Token formats | Format | Shape | Preserves | Validates as | Best for | | ----------- | --------------------- | ---------------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | **generic** | `tok_` | nothing — opaque | nothing — opaque | Default. JSON blobs, free-text PII, API tokens. | | **pan** | 16 digits | first 6 (BIN) + last 4 | Luhn-valid card number | PCI scope reduction in card-shape DB columns. | | **ssn** | NNN-NN-NNNN | last 4 | SSN-shape | US contractor / customer onboarding. Token always starts with 9 (SSA reserves 9XX, so guaranteed not to collide with real SSNs). | | **email** | `@` | domain (lowercased) | RFC-shape email | Marketing/analytics that key on email domain but shouldn't see local-parts. | The `pan` and `ssn` generators solve the math so the resulting token validates: PAN tokens pass the Luhn check, SSN tokens fit the regex your form already enforces. You drop the token into the same column the original would have gone in. ## Encryption + rotation Each vault has its own encryption key (managed via [Crypto Keys](/essentials/crypto-keys/crypto-keys-overview)). Tokens carry the key version they were encrypted under. When you rotate: * A new key version becomes active. * New tokens encrypt under the new version. * Existing tokens still decrypt under their original version (no migration needed). Destroying a vault destroys every key version. Tokens become permanently unreadable. This is **cryptographic erasure** — the data is unrecoverable even if the encrypted ciphertext is leaked from a backup. ## Bulk and TTL * **Bulk tokenize**: up to 1000 values per call via `POST /v1/vaults/{name}/tokens/bulk`. Wraps each tokenize in the same DB transaction. * **TTL**: per-vault default + per-call override. Expired tokens 404 on detokenize and get pruned by an hourly cron. * **Metadata**: attach a small JSON object alongside each token (read back on detokenize). Encrypted at rest. ## Plan limits | Tier | Vaults | Tokens | Format-preserving | Tokenize ops/mo | Detokenize ops/mo | | ---------- | --------- | --------- | --------------------------- | --------------- | ----------------- | | Free | 1 | 1k | generic only | 1k | 1k | | Starter | 5 | 50k | generic only | 10k | 10k | | Pro | 25 | 1M | all (`pan`, `ssn`, `email`) | 1M | 1M | | Enterprise | unlimited | unlimited | all | unlimited | unlimited | ## Next steps * [Crypto Keys overview →](/essentials/crypto-keys/crypto-keys-overview) — the encryption layer Vaults builds on * [API reference →](/api-reference/overview)