Skip to main content
POST/crypto/decrypt

Decrypt

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_KEY for a ciphertext sealed under a key that has since been retired (rewrap it while context.resealableUntil allows).

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 crypto and 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_REQUIRED with 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.

Parameters
projectSlug *path

The project's slug: the path segment after @.

It is unique within the org.

Request body
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

contextstring

Optional caller-chosen context, at most 256 bytes; the same value is needed to decrypt

Responses
HTTPK9O CodeDescription
200Success
400K9O_INVALID_FIELD_VALUEThe 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.
401K9O_UNAUTHENTICATEDThe caller is not authenticated.
401K9O_STEP_UP_REQUIREDA 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.
401K9O_STEP_UP_PROOF_MALFORMEDThe step-up proof was rejected (including a proof already used).
403K9O_ACCESS_DENIEDThe 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.
403K9O_IAM_POLICY_DENIEDThe caller's policy does not allow this crypto action on this crypt.
403K9O_EXTENSION_PERMISSION_DENIEDExtensions use k9o.kibo.encrypt and k9o.kibo.decrypt instead.
403K9O_RBAC_DENYEnd users cannot call this API.
403K9O_PAT_COLLECTION_NOT_PERMITTEDThe personal access token is scoped to other `crypto` crypts.
409K9O_ZK_STORE_FLOW_REQUIREDThis 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.
410K9O_PROJECT_ZEROIZEDThe project's key has been zeroized; nothing can be sealed or opened under it.
413K9O_PAYLOAD_TOO_LARGEAn item is over 64 KiB, or the call is over 1 MiB (context.scope says which).
429K9O_RATE_LIMITEDThe project is over its rate of crypto items; retry after the Retry-After seconds.
503K9O_KEY_SERVICE_UNAVAILABLEThe key service could not complete the call. Nothing was returned; retry.
503K9O_BYOK_KEY_UNREACHABLEThe project's cloud KMS key cannot be reached.
503K9O_HYOK_CLUSTER_UNREACHABLENo host of the project's HSM cluster can be reached.
Response body (200)
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

resealableUntilstring <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 code, for logs.

Branch on code, not on this text.

context *object

Empty, except resealableUntil on K9O_SEALED_UNDER_RETIRED_KEY

meta *any
TypeScript
// 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

Request example
{
  "crypt": "customer-pii",
  "items": [
    {
      "ciphertext": "AQEB…",
      "context": "user:usr_8f2k"
    }
  ]
}
Response example (200)
{
  "data": {
    "items": [
      {
        "plaintext": "string",
        "resealableUntil": "string"
      }
    ]
  }
}

More in Encryption