/crypto/decryptDecrypt
Decrypts up to 100 ciphertexts made by this API, with the same crypt and context used to encrypt them.
Returns items in order; each is either a base64 plaintext or a failure { code, message, context }:
K9O_ENVELOPE_INTEGRITY_FAILURE, with no further detail, for anything that cannot be opened (a different crypt or context, a changed or malformed ciphertext, another project's).K9O_SEALED_UNDER_RETIRED_KEYfor a ciphertext sealed under a key that has since been retired (rewrap it whilecontext.resealableUntilallows).
If the project has moved to its own KMS, a ciphertext still sealed under the old platform key opens until its deadline, and its item also carries resealableUntil: re-seal it client-side before then.
Requires the crypto decrypt permission on the crypt (project editors and admins by default), held through project membership: an org role alone does not count.
Who can call it:
- A service token created with this crypt in its
crypts. - A workload whose bound policy allows it on this crypt.
- A personal access token scoped to resource class
cryptoand this crypt (minting one requires step-up). - A signed-in session that completes a step-up for this crypt and operation, one proof per call (the first request answers 401
K9O_STEP_UP_REQUIREDwith the challenge; retry it with the proof).
An unscoped personal access token is refused (crypto_requires_scoped_pat).
A call that ran answers 200, even if some or all of its items failed.
This API serves platform-managed keys.
A project whose key is held in your own cloud KMS gets 409 K9O_ZK_STORE_FLOW_REQUIRED for the whole call: use the SDK's client-side kibo.encrypt / kibo.decrypt, which call your KMS directly.
Under self-deployed hold-your-own-key custody the key operations run in your HSM, so calls take longer, and an HSM that cannot be reached fails the whole call.
Ciphertext from this API cannot be opened by client-side Kibo or by an extension's k9o.kibo.encrypt, and theirs cannot be opened here.
| projectSlug * | path | The project's slug: the path segment after It is unique within the org. |
| crypt * | string | The crypt: the authorisation unit, bound into the ciphertext |
| items * | object[] | The values to process, 1 to 100. Each is handled on its own, and the answer has one entry per item, in the same order. |
| ciphertext * | string | A ciphertext from this resource, standard base64 |
| context | string | Optional caller-chosen context, at most 256 bytes; the same value is needed to decrypt |
| HTTP | K9O Code | Description |
|---|---|---|
| 200 | Success | |
| 400 | K9O_INVALID_FIELD_VALUE | The body is not exactly { crypt, items }, crypt does not match ^[a-z0-9-]{1,64}$, items is not 1 to 100 objects of the expected field and an optional context, a value is not standard base64, or a context is over 256 bytes. |
| 401 | K9O_UNAUTHENTICATED | The caller is not authenticated. |
| 401 | K9O_STEP_UP_REQUIRED | A signed-in session must complete a step-up for this crypt and operation; context.stepUp carries the challenge. Retry the same request with the proof. |
| 401 | K9O_STEP_UP_PROOF_MALFORMED | The step-up proof was rejected (including a proof already used). |
| 403 | K9O_ACCESS_DENIED | The caller is not an accepted member of this project (an org role alone does not count). context.reason `crypto_requires_scoped_pat`: a personal access token not scoped to resource class `crypto` and this call's crypts. context.reason `crypt_not_provisioned`: a service token whose `crypts` do not include this crypt. |
| 403 | K9O_IAM_POLICY_DENIED | The caller's policy does not allow this crypto action on this crypt. |
| 403 | K9O_EXTENSION_PERMISSION_DENIED | Extensions use k9o.kibo.encrypt and k9o.kibo.decrypt instead. |
| 403 | K9O_RBAC_DENY | End users cannot call this API. |
| 403 | K9O_PAT_COLLECTION_NOT_PERMITTED | The personal access token is scoped to other `crypto` crypts. |
| 409 | K9O_ZK_STORE_FLOW_REQUIRED | This project's key is held in your own KMS (bring or hold your own key, managed by the platform). This API serves platform-managed keys only; use the SDK's client-side kibo.encrypt / kibo.decrypt, which call your KMS directly. The whole call is refused; no item is processed. The response `context` is: ``` { route: "client", custodyMode?: "PLATFORM_MANAGED" | "SKR" | "BYOK" | "HYOK" } ``` custodyMode is the project's custody mode, left out when it is not known. recommendation: { action } says the same in words. |
| 410 | K9O_PROJECT_ZEROIZED | The project's key has been zeroized; nothing can be sealed or opened under it. |
| 413 | K9O_PAYLOAD_TOO_LARGE | An item is over 64 KiB, or the call is over 1 MiB (context.scope says which). |
| 429 | K9O_RATE_LIMITED | The project is over its rate of crypto items; retry after the Retry-After seconds. |
| 503 | K9O_KEY_SERVICE_UNAVAILABLE | The key service could not complete the call. Nothing was returned; retry. |
| 503 | K9O_BYOK_KEY_UNREACHABLE | The project's cloud KMS key cannot be reached. |
| 503 | K9O_HYOK_CLUSTER_UNREACHABLE | No host of the project's HSM cluster can be reached. |
| data * | object | The result for each item. |
| items * | any[] | One entry per request item, in order. The call is 200 whether some or all items failed. |
| One of: object | ||
| plaintext * | string | standard base64 |
| resealableUntil | string <date-time> | Present only when the project moved to its own KMS and this ciphertext is still sealed under the old platform key: re-seal it client-side before this time, after which it can no longer be opened. |
| or: object | ||
| code * | string | K9O_ENVELOPE_INTEGRITY_FAILURE (cannot be opened; no further detail) or K9O_SEALED_UNDER_RETIRED_KEY (rewrap it) |
| message * | string | A readable explanation of Branch on |
| context * | object | Empty, except resealableUntil on K9O_SEALED_UNDER_RETIRED_KEY |
| meta * | any | |
// const k9o = new K9o({ orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…' })
const { data } = await k9o.crypto.decrypt({
crypt: 'customer-pii',
items: [{
ciphertext: 'AQEB…',
context: 'user:usr_8f2k'
}]
})Showing example in TypeScript
{
"crypt": "customer-pii",
"items": [
{
"ciphertext": "AQEB…",
"context": "user:usr_8f2k"
}
]
}{
"data": {
"items": [
{
"plaintext": "string",
"resealableUntil": "string"
}
]
}
}