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
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
- Create a vault with a chosen token format. The format is locked at creation — changing it later would invalidate every existing token.
- 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.
- Detokenize when you need the original:
GET /v1/vaults/{name}/tokens/{token}. Audited every time.
- 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.
- Destroy a vault to cryptographically shred every token in it. Permanently unreadable.
Quick start (UI)
- Go to Protect → Vaults in the admin UI and click New Vault.
- 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.
- Optional: set a default TTL so tokens auto-expire.
- 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.
# 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": "tok_01abc...", "token": "411111ABCDEFGH1111", "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/411111ABCDEFGH1111 \
-H "Authorization: Bearer $KC_API_KEY"
# → data: { "id": "tok_01abc...", "token": "411111ABCDEFGH1111", "value": "4111111111111111",
# "value_b64": "NDExMTExMTExMTExMTExMQ==", "metadata": null,
# "expires_at": null, "created_at": "...", "crypto_key_version": 1 }
| Format | Shape | Preserves | Validates as | Best for |
|---|
| generic | tok_<random base32> | 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 | <token>@<domain> | domain (lowercased) | RFC-shape email | Marketing/analytics that key on email domain but shouldn’t see local-parts. |
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). 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
