Portable Encryption overview

KnoxCall’s Portable Encryption turns any value into a single, self-describing kc: ciphertext string you can drop into a database column, a log line, or a message queue with no schema change — and which carries everything needed to decrypt it except the private key. It is public-key encryption: you encrypt against a tenant public key, and only KnoxCall (holding the matching private key, wrapped under your tenant master key) can decrypt. That means plaintext can be sealed before it ever reaches KnoxCall — including in a browser. Use it for:

“Encrypt anything, store it anywhere” — PII, PHI, PAN, API responses, free-form blobs. The ciphertext is portable across systems.
Structure-preserving encryption — send a whole JSON object; get the same shape back with every scalar leaf replaced by a kc: string.
Frontend scope reduction — seal card/PII data in the page so it never touches your servers (paired with the browser SDK).
Crypto-agility — every kc: value carries its scheme version, so the format can evolve without breaking stored data.

Quick example

# Mint a 1-hour OAuth token (client_credentials) — see /api-reference/authentication
TOKEN=$(curl -s -X POST https://api.knoxcall.com/oauth/token \
  -u "$KNOXCALL_CLIENT_ID:$KNOXCALL_CLIENT_SECRET" \
  -d "grant_type=client_credentials" | jq -r .access_token)

# Encrypt — structure-preserving. Scalar leaves become kc: strings.
curl -X POST https://api.knoxcall.com/v1/encrypt \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "data": { "card": "4242424242424242", "amount": 1299 } }'
# → { "data": { "card": "kc:1:s:...:$", "amount": "kc:1:n:...:$" }, "key": "kc-default", "key_version": 1 }

# Decrypt — non-kc values pass through untouched.
curl -X POST https://api.knoxcall.com/v1/decrypt \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "data": { "card": "kc:1:s:...:$", "amount": "kc:1:n:...:$" } }'
# → { "data": { "card": "4242424242424242", "amount": 1299 } }

# Inspect — metadata about a ciphertext WITHOUT decrypting it.
curl -X POST https://api.knoxcall.com/v1/inspect \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "value": "kc:1:s:...:$" }'
# → { "encrypted": true, "scheme": "kc", "version": 1, "datatype": "s", "key_ref": {...}, "fingerprint": "..." }

If you don’t name a key, KnoxCall auto-provisions a default ecdh-p256 key on first use — the happy path is zero-config. To pin a key, pass "key": "my-key" (create it with key_type: "ecdh-p256" via Crypto Keys).

Data roles

Pass an optional role on encrypt to bind a data-role into the ciphertext (e.g. pci, eu). The role is folded into the key derivation, so the value can only be decrypted by presenting the same role — the policy travels with the data, not just at the gateway.

curl ... -d '{ "data": "4242...", "role": "pci" }'   # encrypt under role "pci"
curl ... -d '{ "data": "kc:...:$", "role": "pci" }'  # must pass role "pci" to decrypt

Client-side reveal without an API key

Browsers and agents should never hold a KnoxCall credential. To let a frontend reveal one value, your backend mints a single-use, payload-pinned capability token and hands it over:

# Backend (holds the KnoxCall credential): mint a token bound to exactly one ciphertext.
curl -X POST https://api.knoxcall.com/v1/client-tokens \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "action": "decrypt", "data": "kc:1:s:...:$", "ttl_seconds": 300 }'
# → { "token": "kct_...", "expires_at": "...", "action": "decrypt" }

# Browser (no KnoxCall credential): exchange the token ONCE for the plaintext.
curl -X POST https://api.knoxcall.com/v1/client/decrypt \
  -H "Authorization: Bearer kct_..." -H "Content-Type: application/json" \
  -d '{ "data": "kc:1:s:...:$" }'
# → { "data": "4242424242424242" }

The token is consumed on first use, expires within minutes, and only matches the exact ciphertext it was minted for. A leak reveals at most that one value, once. The same flow works for vault tokens with action: "detokenize" → POST /v1/client/detokenize.

Dual-custody vaults

A vault created with custody_mode: "dual" issues kc: ciphertext as its token and stores no value at all — you keep the ciphertext, KnoxCall keeps only the key. A breach of KnoxCall alone leaks nothing, and detokenize is a pure decrypt (no database lookup).

Learn more

Ciphertext format & cryptographic spec — the exact wire format and algorithms.
Encryption threat model — what the design defends against, and the trust boundaries.

Getting Started

SDKs

Essentials: Routes

Essentials: Ephemeral Proxy

Essentials: Clients

Essentials: Secrets

Essentials: Environments

Essentials: Collections

Essentials: Databases

Essentials: Vaults

Essentials: Inbound Webhooks

Essentials: Rate Limiting

Essentials: Crypto Keys

Essentials: Portable Encryption

Essentials: Certificate Authority

Essentials: Key Management

Essentials: Tenant KMS (BYOK)

Webhooks

Workflows

AI Gateway

Integrations

Security

Monitoring

Advanced Features

Infrastructure

Secret Store Migrations

Account

Troubleshooting

Support

About

Portable Encryption overview

Portable Encryption overview

Quick example

Data roles

Client-side reveal without an API key

Dual-custody vaults

Learn more

​Portable Encryption overview

​Quick example

​Data roles

​Client-side reveal without an API key

​Dual-custody vaults

​Learn more

Portable Encryption overview

Quick example

Data roles

Client-side reveal without an API key

Dual-custody vaults

Learn more