Skip to main content
GET/custody/status

Get 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-nshield or aws-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.verifiedAt and keys are 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.

  • issuer is this project's issuer URL; it never changes, and a move to another region is a new issuer to trust.
  • subjectPattern is <project>:crypt:<crypt>:op:<encrypt|decrypt>: write one trust rule per op class, for example ...:op:encrypt may only encrypt and ...:op:decrypt may decrypt.
  • audience is the one set on your key attachment (AWS sts.amazonaws.com and Entra api://AzureADTokenExchange by 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).

Parameters
projectSlug *path

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

It is unique within the org.

Responses
HTTPK9O CodeDescription
200Success
401K9O_UNAUTHENTICATEDThe caller is not signed in; authenticate before reading custody status.
403K9O_RBAC_DENYReading custody status requires the PROJECT_ADMIN or PROJECT_AUDITOR project role; org roles do not cascade.
404K9O_NOT_FOUNDNo project with this slug, or the caller is not a member of it.
502K9O_UPSTREAM_UNAVAILABLEThe project is in attached HYOK custody and the key service could not be read for the hsm block; retry later.
Response body (200)
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 BYOK and HYOK this is the mode of the last completed key-service job, so it can trail a transition that is still running.

attached *boolean

True when the mode is BYOK or HYOK and a completed key-service job attached the external key.

Always false for PLATFORM_MANAGED and SKR.

provider *any

Who holds the root key: platform for PLATFORM_MANAGED and SKR, external_kms for an attached BYOK key, hsm for an attached HYOK key.

Null for BYOK or HYOK with no key attached.

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"

transition for a move between PLATFORM_MANAGED and SKR; external_transition for a job that attaches or changes a BYOK or HYOK key.

status *"pending" | "running" | "completed" | "failed"

Where the job stands.

An external_transition is pending, completed or failed; only a transition reports running.

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 provider is hsm; null otherwise.

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 BYOK or HYOK project on a platform-operated deployment.

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 sub claim to write your cloud's trust rule against. <crypt> stands for a key ring id and the last part is encrypt or decrypt.

audience *any

The aud set on the key attachment.

Null when the attachment records none.

One of: string
or: null
or: null
meta *any
TypeScript
// const k9o = new K9o({ orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…' })
const { data } = await k9o.custody.status()

Showing example in TypeScript

Response example (200)
{
  "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"
    }
  }
}

More in Encryption