Docs / API reference

Keys & crypto

Key lifecycle management, plus the two encryption paths described in the architecture guide: the legacy deterministic scheme, and the randomized scheme used by the vault-backed data path.

See how the two schemes differ
POST/key/generateAuthenticated

Creates a new encryption key for a user. Idempotent — calling it again for a user who already has one returns their existing status instead of creating a duplicate.

Response 200
{ "userId": "usr_8f2a1c", "status": "GENERATED" }
GET/key-status/:userIdAuthenticated

Returns a user's current key lifecycle status.

NameInTypeRequiredDescription
userIdpathstringYesThe user to look up.
Response 200
{ "userId": "usr_8f2a1c", "status": "ACTIVE" }
  • status is one of ACTIVE, ROTATED, or SHREDDED.
DELETE/key/shredAuthenticated

Destroys a user's key material — the mathematical-erasure operation that starts the deletion lifecycle.

  • Permanent and irreversible. Subsequent /encrypt and /decrypt calls for this user return 404.
  • This is a synchronous key-material erasure, not a Cloud KMS key-version destroy — see the crypto-shredding guide for exactly what that distinction means.
POST/key/rotateAuthenticated

Generates a new key version for a user.

  • Existing ciphertext is not automatically re-encrypted under the new version.
GET/key/:userId/encryption-contextAuthenticated

Returns wrapped key material and algorithm metadata a data pipeline needs to perform local encryption or tokenization.

NameInTypeRequiredDescription
userIdpathstringYesThe user to fetch an encryption context for.
Response 200
{
  "userId": "usr_8f2a1c",
  "keyVersionId": "v1",
  "wrappedDek": "<base64-encoded, key-wrapped DEK>",
  "algorithm": "AES-256-GCM",
  "tokenization": { "algorithm": "HMAC-SHA256", "tokenKeyId": "tok_v1" }
}

Legacy vs. current encryption paths

The two routes below use the deterministic scheme and are marked demo-only in Chameleon's own API spec — same plaintext always produces identical ciphertext per user. Real ingested PII uses the randomized scheme instead, via the vault-decrypt route beneath them. See the architecture guide for the full comparison.

POST/encryptPer-analyst credential

[Demo only] Encrypts plaintext using the deterministic AES-256-GCM scheme, returning a compound "<keyVersionId>:<base64>" ciphertext string.

POST/decryptPer-analyst credential

[Demo only] Decrypts a ciphertext produced by /encrypt, verifying its authentication tag.

  • Requires the exact compound ciphertext string returned by /encrypt, including the key-version prefix.
POST/pii-vault/decryptAuthenticated

Decrypts a field from the central vault on demand, using the randomized encryption scheme real ingested PII actually uses.

  • Only available when this deployment has vault-decrypt configured — otherwise this route doesn't exist.
Keep reading