Skip to main content
GET/crypto/mode

Get Crypto Mode

Returns the project's key custody mode (PLATFORM_MANAGED, SKR, BYOK or HYOK), its route, and an opaque epoch that changes with every custody transition.

Call it before every encrypt, with no caching.

route says where the encrypt runs, either server (POST /crypto/encrypt, sending this epoch as custodyEpoch) or client (in your process against your own KMS).

Follow route, not the mode: a self-deployed BYOK or HYOK project is server.

If custody moves between this check and the encrypt, the encrypt is refused with 409 K9O_ZK_STORE_FLOW_REQUIRED before any key work, carrying the new mode, route and epoch; check again.

Always pass the crypt your next encrypt will use (the SDK does): the caller must be allowed to encrypt on it.

Without it, the caller needs a crypto grant on every crypt, so a caller whose bound policy names only specific crypts must pass crypt.

Extensions and end users are refused.

Returns nothing else about the project's custody.

Parameters
cryptquery

The crypt the next encrypt will use; always pass it (the SDK does).

Without it the caller needs a crypto grant on every crypt, so a bound policy naming only specific crypts must pass it

projectSlug *path

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

It is unique within the org.

Responses
HTTPK9O CodeDescription
200Success
400K9O_INVALID_FIELD_VALUEcrypt does not match ^[a-z0-9-]{1,64}$.
401K9O_UNAUTHENTICATEDThe caller is not authenticated.
403K9O_ACCESS_DENIEDThe caller has no access to this project.
403K9O_IAM_POLICY_DENIEDThe caller may not encrypt on this crypt (or, without crypt, on every crypt).
403K9O_PAT_COLLECTION_NOT_PERMITTEDA personal access token scoped to named crypts asked about another crypt, or about every crypt.
403K9O_EXTENSION_PERMISSION_DENIEDExtensions use k9o.kibo, not the crypto resource.
403K9O_RBAC_DENYEnd users cannot call the crypto resource.
410K9O_PROJECT_ZEROIZEDThe project's key has been zeroized.
503K9O_KEY_SERVICE_UNAVAILABLEThe key service could not answer. No mode means no encrypt; retry.
Response body (200)
data *object

How the project's next encrypt must run, and the custody epoch to send with it.

custodyMode *"PLATFORM_MANAGED" | "SKR" | "BYOK" | "HYOK"

The project's key custody mode

route *"client" | "server"

Where the next encrypt runs: client in your process against your own KMS, server through POST /crypto/encrypt.

Follow this, not custodyMode

epoch *string

Opaque; changes with every custody transition.

Send it as custodyEpoch on the encrypt this check precedes

meta *any
TypeScript
// const k9o = new K9o({ orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…' })
const { data } = await k9o.crypto.mode()

Showing example in TypeScript

Response example (200)
{
  "data": {
    "custodyMode": "PLATFORM_MANAGED",
    "route": "client",
    "epoch": "string"
  }
}

More in Encryption