/custody/statusGet Custody Status
Read-only summary of the project's key custody: { mode, attached, provider, lastJob, hsm, kmsFederation }. provider is platform (PLATFORM_MANAGED or SKR), external_kms (attached BYOK), hsm (attached HYOK) or null (an external mode with nothing attached). lastJob is { kind: "transition" | "external_transition", status, completedAt } or null.
hsm is null unless provider is hsm.
For an attached HYOK project it is:
{ vendor, clusterId, region, attestation: { status, verifiedAt }, keys }vendor: the HSM model registered for the cluster's hosts (thales-luna,entrust-nshieldoraws-cloudhsm); null when the hosts disagree or for a cloud-HSM provider.clusterId: the attached HYOK cluster; null for a cloud-HSM provider, which attaches a key directly.region: the cluster's registered region; null for a cloud-HSM provider.attestation.status,attestation.verifiedAtandkeysare always null: the key service doesn't report an attestation result or the customer key's id, version, state or rotation time. null means not known, not empty.
No key material and no certificate, credential or secret reference is ever returned.
kmsFederation is set for an attached BYOK or HYOK project whose keys are used client-side, and null otherwise: { issuer, subjectPattern, audience }, what your cloud trusts for the federated token.
issueris this project's issuer URL; it never changes, and a move to another region is a new issuer to trust.subjectPatternis<project>:crypt:<crypt>:op:<encrypt|decrypt>: write one trust rule per op class, for example...:op:encryptmay only encrypt and...:op:decryptmay decrypt.audienceis the one set on your key attachment (AWSsts.amazonaws.comand Entraapi://AzureADTokenExchangeby default; GCP has none until you set the workload identity pool provider).
Entra federated credentials need RS256 (used) and match sub exactly, with no wildcards, and an app holds at most 20 of them: one per crypt and op class you use.
Read-only.
Requires the PROJECT_ADMIN or PROJECT_AUDITOR project role (project membership; org roles do not cascade).
For an attached HYOK project the key service is read; if it cannot be read the answer is 502 K9O_UPSTREAM_UNAVAILABLE.
A caller with no project membership gets 404 (no existence leak).
| projectSlug * | path | The project's slug: the path segment after It is unique within the org. |
| HTTP | K9O Code | Description |
|---|---|---|
| 200 | Success | |
| 401 | K9O_UNAUTHENTICATED | The caller is not signed in; authenticate before reading custody status. |
| 403 | K9O_RBAC_DENY | Reading custody status requires the PROJECT_ADMIN or PROJECT_AUDITOR project role; org roles do not cascade. |
| 404 | K9O_NOT_FOUND | No project with this slug, or the caller is not a member of it. |
| 502 | K9O_UPSTREAM_UNAVAILABLE | The project is in attached HYOK custody and the key service could not be read for the hsm block; retry later. |
| data * | object | The project's key custody mode, who holds the root key, and the state of the last key-service job. |
| mode * | "PLATFORM_MANAGED" | "SKR" | "BYOK" | "HYOK" | The project's key custody mode. For |
| attached * | boolean | True when the mode is Always false for |
| provider * | any | Who holds the root key: Null for |
| One of: "platform" | ||
| or: "external_kms" | ||
| or: "hsm" | ||
| or: null | ||
| lastJob * | any | The project's most recent custody job of either kind. Null when the project has never run one. |
| One of: object | ||
| kind * | "transition" | "external_transition" |
|
| status * | "pending" | "running" | "completed" | "failed" | Where the job stands. An |
| completedAt * | any | When the job finished. Null while it is still pending or running. |
| One of: string <date-time> | ||
| or: null | ||
| or: null | ||
| hsm * | any | HSM details. Present only when |
| One of: object | ||
| vendor * | any | The HSM model of the attached cluster's hosts. Null when it isn't recorded, or when the hosts don't all report the same model. |
| One of: "thales-luna" | ||
| or: "entrust-nshield" | ||
| or: "aws-cloudhsm" | ||
| or: null | ||
| clusterId * | any | The id of the attached HSM cluster. Null for cloud HSM providers, which have no cluster record. |
| One of: string | ||
| or: null | ||
| region * | any | The region recorded for the HSM cluster. Null when there is no cluster or no region recorded. |
| One of: string | ||
| or: null | ||
| attestation * | object | HSM attestation. Both fields are null because the platform records no verified attestation. |
| status * | null | Always null: no verified attestation status is recorded. |
| verifiedAt * | null | Always null: no attestation verification time is recorded. |
| keys * | null | Always null: customer key versions and rotation state are not recorded by the platform. |
| or: null | ||
| kmsFederation * | any | What your cloud must trust so the platform can use your key. Set for an attached Null otherwise, and null when the federation settings can't be read. |
| One of: object | ||
| issuer * | string | The issuer URL of the tokens the platform presents to your cloud for this project. It never changes. Your cloud's trust rule names it. |
| subjectPattern * | string | The pattern of the |
| audience * | any | The Null when the attachment records none. |
| One of: string | ||
| or: null | ||
| or: null | ||
| meta * | any | |
// const k9o = new K9o({ orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…' })
const { data } = await k9o.custody.status()Showing example in TypeScript
{
"data": {
"mode": "PLATFORM_MANAGED",
"attached": false,
"provider": "platform",
"lastJob": {
"kind": "transition",
"status": "pending",
"completedAt": "string"
},
"hsm": {
"vendor": "thales-luna",
"clusterId": "string",
"region": "string",
"attestation": {}
},
"kmsFederation": {
"issuer": "string",
"subjectPattern": "string",
"audience": "string"
}
}
}