Skip to main content
POST/crypto/encrypt

Encrypt

Encrypts up to 100 items with the project's key; the key never leaves the platform and you never choose one.

Read the project's custody mode and custodyEpoch from GET /crypto/mode first, and send that custodyEpoch.

Send a crypt (lowercase letters, digits and hyphens, up to 64 characters), the unit you grant access on, and items, each a base64 plaintext of at most 64 KiB (1 MiB per call) with an optional context of up to 256 bytes.

Returns items, one opaque, base64 ciphertext per item, in order.

Decrypting needs the same crypt and context.

Requires the crypto encrypt permission on the crypt (project editors and admins by default), held through project membership: an org role alone does not count.

A personal access token scoped to crypto crypts encrypts only under those crypts.

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.

Erasure: this ciphertext becomes unreadable everywhere when the project's key is zeroized or the project is purged.

It is not covered by per-subject erasure, because the platform does not know whose data you encrypted.

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

custodyEpoch *string

Required.

The custody epoch from GET /crypto/mode, opaque.

If the project's key custody has changed since, the call is refused (409 K9O_ZK_STORE_FLOW_REQUIRED) with the current mode, route and epoch

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.

plaintext *string

The data, 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.
400K9O_INVALID_REQUEST_SHAPEThe body does not match the schema; context.detail names each field. A missing or malformed `custodyEpoch` (^[A-Za-z0-9_.:-]{1,128}$) is refused here.
401K9O_UNAUTHENTICATEDThe caller is not authenticated.
403K9O_ACCESS_DENIEDThe caller is not an accepted member of this project (an org role alone does not count).
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.
404K9O_CRYPT_NOT_FOUNDThe crypt is not registered in this project: create it first with POST /crypto/crypts.
409K9O_ZK_STORE_FLOW_REQUIREDRefused before any key work, for the whole call, in two cases: 1. The project's key is held in your own cloud KMS: this API serves platform-managed keys only, so use the SDK's client-side kibo.encrypt / kibo.decrypt, which call your KMS directly. 2. `custodyEpoch` is not the project's current custody epoch: custody changed since you read it. The response `context` is: ``` { route: "client" | "server", custodyMode?: "PLATFORM_MANAGED" | "SKR" | "BYOK" | "HYOK", epoch?: the current custody epoch } ``` custodyMode is left out when it is not known; epoch is set when the refusal is a stale epoch. recommendation: { action }.
409K9O_CRYPT_RETIREDThe crypt is retired. Decrypt and rewrap still work; encrypt doesn't.
409K9O_BYOK_REGION_MISMATCHThe project's customer-managed key does not cover the region this request is served in, so nothing was sealed; the key is never replaced with a platform key.
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
ciphertext *string

standard base64

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.encrypt({
  crypt: 'customer-pii',
  custodyEpoch: '42',
  items: [{
    plaintext: 'YWxpY2VAZXhhbXBsZS5jb20=',
    context: 'user:usr_8f2k'
  }]
})

Showing example in TypeScript

Request example
{
  "crypt": "customer-pii",
  "custodyEpoch": "42",
  "items": [
    {
      "plaintext": "YWxpY2VAZXhhbXBsZS5jb20=",
      "context": "user:usr_8f2k"
    }
  ]
}
Response example (200)
{
  "data": {
    "items": [
      {
        "ciphertext": "string"
      }
    ]
  }
}

More in Encryption