/crypto/modeGet 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.
| crypt | query | 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. |
| HTTP | K9O Code | Description |
|---|---|---|
| 200 | Success | |
| 400 | K9O_INVALID_FIELD_VALUE | crypt does not match ^[a-z0-9-]{1,64}$. |
| 401 | K9O_UNAUTHENTICATED | The caller is not authenticated. |
| 403 | K9O_ACCESS_DENIED | The caller has no access to this project. |
| 403 | K9O_IAM_POLICY_DENIED | The caller may not encrypt on this crypt (or, without crypt, on every crypt). |
| 403 | K9O_PAT_COLLECTION_NOT_PERMITTED | A personal access token scoped to named crypts asked about another crypt, or about every crypt. |
| 403 | K9O_EXTENSION_PERMISSION_DENIED | Extensions use k9o.kibo, not the crypto resource. |
| 403 | K9O_RBAC_DENY | End users cannot call the crypto resource. |
| 410 | K9O_PROJECT_ZEROIZED | The project's key has been zeroized. |
| 503 | K9O_KEY_SERVICE_UNAVAILABLE | The key service could not answer. No mode means no encrypt; retry. |
| 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: Follow this, not custodyMode |
| epoch * | string | Opaque; changes with every custody transition. Send it as custodyEpoch on the encrypt this check precedes |
| meta * | any |
// const k9o = new K9o({ orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…' })
const { data } = await k9o.crypto.mode()Showing example in TypeScript
{
"data": {
"custodyMode": "PLATFORM_MANAGED",
"route": "client",
"epoch": "string"
}
}