Skip to main content
POST/crypto/rewrap

Rewrap

Re-seals up to 100 ciphertexts under the project's current key in one call; the plaintext never leaves the platform.

Use it after a key rotation, and for ciphertexts that decrypt answers with K9O_SEALED_UNDER_RETIRED_KEY.

Send the same crypt and context used to encrypt.

Returns items in order; each is a new base64 ciphertext or a failure { code, message, context }, as for decrypt.

Requires the crypto rewrap 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.

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
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.rewrap({
  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": [
      {
        "ciphertext": "string"
      }
    ]
  }
}

More in Encryption