Skip to main content

POST /api/v1/crypto/encrypt

Encrypt data, optionally minting a new key.

Encrypts data. If ttag is omitted the key server mints a new key, and the ttag in the response is the only handle to it -- without it the ciphertext cannot ever be decrypted. minted in the response says which happened.

WARNING: ttag: "" is refused rather than treated as omitted. An empty string reaches the wire as the zero-length buffer that means "mint a new key", so a caller who sent one by accident would silently mint a key instead of using theirs. Omit the field entirely to mint deliberately.

The ttag is echoed in the response because the underlying binding bolts it onto the ciphertext buffer as a property rather than returning a pair, and any copy of that buffer loses it.

On a scoped credential the ttag must be in the credential's object list. A mint (no ttag) names no object and is therefore not scope-checked.

Authentication​

Send the session id as Authorization: Bearer <session id>, and an RFC 9449 DPoP proof in the DPoP header if your session is bound to a key. The two are required together, not as alternatives — see Authenticating and Proving you hold your key.

This surface sets no cookie

There is no session cookie on any response and none is read on any request. Do not set credentials: "include" on a browser fetch.

Request​

FieldTypeRequiredDescription
datastringyesCanonical base64.
ttagstringnoCanonical base64 hidden link. OMIT to mint a new key. Do not send an empty string.
ivstringnoCanonical base64. Optional.

Example

{
  "data": "...",
  "ttag": "...",
  "iv": "..."
}

Responses​

200​

Encrypted.

FieldTypeRequiredDescription
ciphertextstringyesbase64
ttagstringyesbase64. When minted is true this is the ONLY handle to the new key. Store it before doing anything else.
mintedbooleanyes
ivSuppliedbooleanno
plaintextBytesintegerno
ciphertextBytesintegerno
detailstringyes

Example

{
  "ciphertext": "...",
  "ttag": "...",
  "minted": true,
  "ivSupplied": true,
  "plaintextBytes": 0,
  "ciphertextBytes": 0,
  "detail": "..."
}

400​

BAD_REQUEST -- data absent or not canonical base64, ttag empty-string, a malformed iv, or data larger than 16,777,215 bytes decoded. That is the largest plaintext one request carries: its ciphertext comes back in a single field of at most 16 MiB. A larger plaintext is refused here, whether or not a ttag is named, before the scope check and before anything reaches the key server, so no key is created for it. Encrypt a larger payload in parts.

401​

The session, or the DPoP proof, or SCOPED_CREDENTIAL_EXPIRED. See the shared Unauthorized description.

403​

OBJECT_NOT_IN_CREDENTIAL_SCOPE -- this scoped credential was not minted to cover that ttag. This is not a statement about your rights: whether the principal may reach the object is the key server's answer and it has not been asked; nothing was sent. Or ACCESS_DENIED from the key server itself.

410​

KEY_EXPIRED (retryable: false) -- the key the request named was expired (POST /api/v1/keys/expire). Its record is kept, and every use of it -- decrypt, encrypt under its t-Tag, export, an access-control grant or update -- is refused, on every key server of the deployment. An expiry is never undone; the key's owner may still remove it.

500​

A fault rather than a refusal.

OP_FAILED is the catch-all: the key server refused in words that match no classified pattern, so the Gateway cannot say more than that the operation did not happen. Some key server refusals that are conceptually a caller error arrive here rather than as a 4xx, because the wire carries no distinguishing code -- where a route can recognise one from its message it maps it, and each such mapping is documented on the operation.

503​

A capacity ceiling or a missing deployment prerequisite. retryable says which.

A scope of session or process names the ceiling that was hit, and the response carries Retry-After.

BUILD_NOT_ADMITTED (scope: process, retryable: true, Retry-After): the key server does not admit this Gateway's client build. Every key-server connection the Gateway opens attests the signed release it runs (TE_RELEASE_MANIFEST) right after it authenticates; while that attestation is refused -- the release is not registered at the key server's code-signing level, the level was raised under it, or the installed files no longer match the signed manifest -- every route but GET /api/v1/health and GET /api/v1/ready answers this, and detail names the cause. It is never a 401 or a 403: no credential or role of the caller's is at fault. The Gateway re-attempts on a timer and recovers without a restart once the key server admits it; GET /api/v1/ready says when.

CAPACITY_UNAVAILABLE (scope: process, retryable: true, Retry-After): this Gateway is serving its maximum number of requests at once, or cannot track another allowance, or (on a certificate login) is recording its maximum of live certificate sessions -- in which case the session the login created has been closed. Nothing else was sent to the key server. See "Rate and capacity limits" above.

413​

PAYLOAD_TOO_LARGE (retryable: false) -- the request body is larger than this deployment accepts. It was refused before it was parsed, and the connection is closed. Nothing was sent to the key server.

429​

RATE_LIMITED (retryable: true, Retry-After) -- the allowance this request is charged to is spent: the login allowance of its network source (before authentication), or the allowance, the concurrency ceiling or the live-session ceiling of the identity it was verified as -- shared by every session that identity holds, including every delegated and scoped credential a service minted. It carries no scope. Nothing was sent to the key server; on a login refused after authentication, the session it created has been closed. See "Rate and capacity limits" above.

Error handling​

Every failure answers JSON carrying at least code and detail. Match on code — detail is written for a human debugging the call and its wording is not part of the contract. See the error model.

StatusMeaning
400BAD_REQUEST -- data absent or not canonical base64, ttag empty-string, a malformed iv, or data larger than 16,777,215 bytes decoded. That is the largest plaintext one request carries: its ciphertext comes back in a single field of at most 16 MiB. A larger plaintext is refused here, whether or not a ttag is named, before the scope check and before anything reaches the key server, so no key is created for it. Encrypt a larger payload in parts.
401The session, or the DPoP proof, or SCOPED_CREDENTIAL_EXPIRED. See the shared Unauthorized description.
403OBJECT_NOT_IN_CREDENTIAL_SCOPE -- this scoped credential was not minted to cover that ttag. This is not a statement about your rights: whether the principal may reach the object is the key server's answer and it has not been asked; nothing was sent. Or ACCESS_DENIED from the key server itself.
410KEY_EXPIRED (retryable: false) -- the key the request named was expired (POST /api/v1/keys/expire). Its record is kept, and every use of it -- decrypt, encrypt under its t-Tag, export, an access-control grant or update -- is refused, on every key server of the deployment. An expiry is never undone; the key's owner may still remove it.
500A fault rather than a refusal. OP_FAILED is the catch-all: the key server refused in words that match no classified pattern, so the Gateway cannot say more than that the operation did not happen. Some key server refusals that are conceptually a caller error arrive here rather than as a 4xx, because the wire carries no distinguishing code -- where a route can recognise one from its message it maps it, and each such mapping is documented on the operation.
503A capacity ceiling or a missing deployment prerequisite. retryable says which. A scope of session or process names the ceiling that was hit, and the response carries Retry-After. BUILD_NOT_ADMITTED (scope: process, retryable: true, Retry-After): the key server does not admit this Gateway's client build. Every key-server connection the Gateway opens attests the signed release it runs (TE_RELEASE_MANIFEST) right after it authenticates; while that attestation is refused -- the release is not registered at the key server's code-signing level, the level was raised under it, or the installed files no longer match the signed manifest -- every route but GET /api/v1/health and GET /api/v1/ready answers this, and detail names the cause. It is never a 401 or a 403: no credential or role of the caller's is at fault. The Gateway re-attempts on a timer and recovers without a restart once the key server admits it; GET /api/v1/ready says when. CAPACITY_UNAVAILABLE (scope: process, retryable: true, Retry-After): this Gateway is serving its maximum number of requests at once, or cannot track another allowance, or (on a certificate login) is recording its maximum of live certificate sessions -- in which case the session the login created has been closed. Nothing else was sent to the key server. See "Rate and capacity limits" above.
413PAYLOAD_TOO_LARGE (retryable: false) -- the request body is larger than this deployment accepts. It was refused before it was parsed, and the connection is closed. Nothing was sent to the key server.
429RATE_LIMITED (retryable: true, Retry-After) -- the allowance this request is charged to is spent: the login allowance of its network source (before authentication), or the allowance, the concurrency ceiling or the live-session ceiling of the identity it was verified as -- shared by every session that identity holds, including every delegated and scoped credential a service minted. It carries no scope. Nothing was sent to the key server; on a login refused after authentication, the session it created has been closed. See "Rate and capacity limits" above.