​

Vaults overview

• 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

​

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)

# 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

​

Encryption + rotation

• A new key version becomes active.
• New tokens encrypt under the new version.
• Existing tokens still decrypt under their original version (no migration needed).

​

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

​

Next steps

• Crypto Keys overview → — the encryption layer Vaults builds on
• API reference →