Skip to main content

​
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

ProblemWithout KnoxCallWith KnoxCall
PAN scattered across 14 microservicesEvery service is in PCI scopeOnly the gateway sees PANs; everything downstream sees tokens
Customer asks for deletion under GDPRHunt every DB + backupDelete the vault key version → cryptographic erasure
Email leak from analytics warehouseReal emails leakTokenized emails leak — domain still useful for routing/cohorts
Format-preserving = build it yourselfHand-rolled FPE = subtle bugsBuilt-in pan (Luhn-valid), ssn (9XX prefix avoids real SSNs), email, generic

​
How it works

  1. Create a vault with a chosen token format. 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. 
# 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

FormatShapePreservesValidates asBest for
generictok_<random base32>nothing — opaquenothing — opaqueDefault. JSON blobs, free-text PII, API tokens.
pan16 digitsfirst 6 (BIN) + last 4Luhn-valid card numberPCI scope reduction in card-shape DB columns.
ssnNNN-NN-NNNNlast 4SSN-shapeUS 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 emailMarketing/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). 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

TierVaultsTokensFormat-preservingTokenize ops/moDetokenize ops/mo
Free11kgeneric only1k1k
Starter550kgeneric only10k10k
Pro251Mall (pan, ssn, email)1M1M
Enterpriseunlimitedunlimitedallunlimitedunlimited

​
Next steps