# Get Custody Status

`GET /custody/status` · Core · Encryption

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

| Name | In | Required | Description |
|---|---|---|---|
| `projectSlug` | path | yes | The project's slug: the path segment after `@`. It is unique within the org. Example: `"storefront"`. |

## Responses

- **200**: Success

| Field | Type | Required | Description |
|---|---|---|---|
| `data` | object | yes | The project's key custody mode, who holds the root key, and the state of the last key-service job. |
| `data.mode` | enum ("PLATFORM_MANAGED", "SKR", "BYOK", "HYOK") | yes | 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. |
| `data.attached` | boolean | yes | 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`. |
| `data.provider` | object | yes | 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_ | | |  |
| _or_ | | |  |
| _or_ | | |  |
| _or_ | | |  |
| `data.lastJob` | object | yes | The project's most recent custody job of either kind. Null when the project has never run one. |
| _one of_ | | |  |
| `data.lastJob.kind` | enum ("transition", "external_transition") | yes | `transition` for a move between `PLATFORM_MANAGED` and `SKR`; `external_transition` for a job that attaches or changes a `BYOK` or `HYOK` key. |
| `data.lastJob.status` | enum ("pending", "running", "completed", "failed") | yes | Where the job stands. An `external_transition` is `pending`, `completed` or `failed`; only a `transition` reports `running`. |
| `data.lastJob.completedAt` | object | yes | When the job finished. Null while it is still pending or running. |
| _one of_ | | |  |
| _or_ | | |  |
| _or_ | | |  |
| `data.hsm` | object | yes | HSM details. Present only when `provider` is `hsm`; null otherwise. |
| _one of_ | | |  |
| `data.hsm.vendor` | object | yes | 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_ | | |  |
| _or_ | | |  |
| _or_ | | |  |
| _or_ | | |  |
| `data.hsm.clusterId` | object | yes | The id of the attached HSM cluster. Null for cloud HSM providers, which have no cluster record. |
| _one of_ | | |  |
| _or_ | | |  |
| `data.hsm.region` | object | yes | The region recorded for the HSM cluster. Null when there is no cluster or no region recorded. |
| _one of_ | | |  |
| _or_ | | |  |
| `data.hsm.attestation` | object | yes | HSM attestation. Both fields are null because the platform records no verified attestation. |
| `data.hsm.attestation.status` | null | yes | Always null: no verified attestation status is recorded. |
| `data.hsm.attestation.verifiedAt` | null | yes | Always null: no attestation verification time is recorded. |
| `data.hsm.keys` | null | yes | Always null: customer key versions and rotation state are not recorded by the platform. |
| _or_ | | |  |
| `data.kmsFederation` | object | yes | 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_ | | |  |
| `data.kmsFederation.issuer` | string | yes | 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. |
| `data.kmsFederation.subjectPattern` | string | yes | 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`. |
| `data.kmsFederation.audience` | object | yes | The `aud` set on the key attachment. Null when the attachment records none. |
| _one of_ | | |  |
| _or_ | | |  |
| _or_ | | |  |
| `meta` | object | yes |  |


## Errors

| HTTP | Code | When |
|---|---|---|
| 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. |

## Code samples

### cURL

```bash
curl -X GET 'https://<org>.api-<region>.k9o.io/@storefront/custody/status' \
  -H 'Authorization: Bearer $K9O_TOKEN'
```

### fetch

```javascript
const res = await fetch('https://<org>.api-<region>.k9o.io/@storefront/custody/status', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.K9O_TOKEN}`
  },
});
const { data, meta } = await res.json();
```

### k9o CLI

```bash
k9o custody status
```

### @k9o/core

```typescript
// const k9o = new K9o({ orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…' })
const { data } = await k9o.custody.status()
```

### k9o

```python
# k9o = create_client(org_slug="playground", project_slug="storefront", api_key="k9o_…")
response = k9o.custody.status()
```

### sdk-go

```go
// ctx := context.Background()
// client, _ := k9o.NewClient(k9o.ClientOpts{OrgSlug: "playground", ProjectSlug: "storefront", APIKey: "k9o_…"})
data, _, kerr := client.Custody.Status(ctx)
```

### k9o

```rust
// let k9o = Client::new(ClientOpts { org_slug: "playground".into(), project_slug: "storefront".into(), api_key: "k9o_…".into() })?;
let resp = k9o.custody.status().await?
```

### dev.k9o:core

```java
// K9o k9o = K9o.createClient(K9o.Opts.builder().orgSlug("playground").projectSlug("storefront").apiKey("k9o_…").build());
var response = k9o.custody().status()
```

### K9o.Core

```c#
// var k9o = K9oClient.Create(new K9oOptions { OrgSlug = "playground", ProjectSlug = "storefront", ApiKey = "k9o_…" });
var response = await k9o.Custody.StatusAsync()
```

### k9o

```ruby
# k9o = K9o.create_client(org_slug: "playground", project_slug: "storefront", api_key: "k9o_…")
response = k9o.custody.status()
```

### k9o/sdk

```php
// $k9o = K9oClient::create(['org_slug' => 'playground', 'project_slug' => 'storefront', 'api_key' => 'k9o_…']);
$response = $k9o->custody->status()
```


Canonical page: https://docs.kilimanjaro.dev/api-playground/core/get-custody-status
