# List Keys

`GET /vault/keys` · Keys & Secrets · Keys

Returns the project's key-encryption key (KEK) versions. Without `status`, only active keys are returned. The list is complete, so `nextCursor` is always null. Needs `PROJECT_ADMIN` or `PROJECT_AUDITOR`.

## Parameters

| Name | In | Required | Description |
|---|---|---|---|
| `projectId` | query | yes | The project's id. Example: `"3f2c9a4e-8b1d-4c6f-9e2a-7d5b1c0a4e8f"`. |
| `status` | query | no | `all` returns every key, retired and revoked ones included. Without it, only active keys. Example: `"all"`. |

## Responses

- **200**: The project's keys.

| Field | Type | Required | Description |
|---|---|---|---|
| `items` | array of object | yes | Page of vault keys. |
| `items.[]byokRef` | object | no |  |
| _one of_ | | |  |
| _or_ | | |  |
| `items.[]byokRef.externalKeyId` | string | yes | Provider-specific external key identifier (e.g., AWS KMS key ARN; GCP Cloud KMS resource path). Example: `"arn:aws:kms:eu-central-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"`. |
| `items.[]byokRef.provider` | string | yes | BYOK provider slug — `"aws-kms"`, `"gcp-cloud-kms"`, `"azure-key-vault"`, or `"vault-transit"`. Example: `"aws-kms"`. |
| `items.[]byokRef.region` | string | yes | The project's region pin (`byok_attachments.region`): the platform region the key was attached for and is region-pinned against (a short code, e.g. `us01`). The key's own provider location is inside `external_key_id` (the ARN or resource path). Example: `"de01"`. |
| `items.[]createdAt` | string (date-time) | yes | Key creation timestamp. Example: `"2026-11-01T08:00:00.000Z"`. |
| `items.[]custodyMode` | enum ("PLATFORM_MANAGED", "CONFIDENTIAL_WORKLOAD", "BYOK", "HYOK") | yes | Custody mode of a project's vault. |
| `items.[]hyokRef` | object | no |  |
| _one of_ | | |  |
| _or_ | | |  |
| `items.[]hyokRef.clusterId` | string | yes | Identifier of the HYOK cluster this key is scoped to. Example: `"hyokcluster_0b6f2c1e-3d4a-4b5c-8d9e-0f1a2b3c4d5e"`. |
| `items.[]hyokRef.clusterName` | string | yes | Human-readable cluster name. Example: `"luna-prod-eu"`. |
| `items.[]hyokRef.keyHandle` | string | yes | HSM-specific opaque key handle. Example: `"e3c5a2b1-7d4f-4a9e-b6c8-1f2e3d4c5b6a"`. |
| `items.[]id` | string | yes | Key identifier — UUID prefixed `"vkey_"`. Example: `"vkey_7Rt2Wq9LxP4m"`. |
| `items.[]keyType` | string | yes | Key type — currently `"AES-256-GCM-SIV"` for all v2 data-encryption keys. Example: `"AES-256-GCM-SIV"`. |
| `items.[]projectId` | string | yes | Project this key belongs to. Example: `"3f2b8c1e-5d4a-4e6f-9a7b-1c2d3e4f5a6b"`. |
| `items.[]purpose` | string | yes | Key purpose. v2 customer-facing inventory keys serve data encryption only; the platform's ledger-signing key is platform-internal and not in this inventory. Example: `"data-encryption"`. |
| `items.[]revokedAt` | string (date-time) \| null | no | Revocation timestamp; null unless `status == "revoked"`. Example: `"2026-11-15T09:30:00.123Z"`. |
| `items.[]rotatedAt` | string (date-time) \| null | no | Last successful rotation completion timestamp; null if never rotated. Example: `"2026-11-15T09:30:00.123Z"`. |
| `items.[]status` | enum ("active", "rotating", "revoked") | yes | Status of a vault key lifecycle (`active \| rotating \| revoked`). |
| `items.[]version` | integer (int64) | yes | Monotone version scalar — starts at 1; incremented on each successful rotation. Example: `3`. |
| `nextCursor` | string \| null | no | Opaque cursor for the next page; `null` when this page is the last. Example: `"eyJpZCI6InZrZXlfMDFIWlg0QTlCMkMzRDRFNUY2RzdIOEo5S00ifQ"`. |


## Errors

| HTTP | Description |
|---|---|
| 401 | The request carries no authenticated caller. |
| 500 | An internal error. Retry later. |

## Code samples

### cURL

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

### fetch

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

### k9o CLI

```bash
k9o keys list
```

### @k9o/core

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

### k9o

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

### sdk-go

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

### dev.k9o:core

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

### K9o.Core

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

### k9o/sdk

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


Canonical page: https://docs.kilimanjaro.dev/api-playground/keys-secrets/list-keys
