# List Secrets

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

Returns a page of the secrets the caller owns or that are shared with them, in path order, without their values. `prefix` narrows the list to one branch of paths. Follow `nextCursor` until it is null to read every page.

## Parameters

| Name | In | Required | Description |
|---|---|---|---|
| `projectId` | query | yes | The project's id. Example: `"3f2c9a4e-8b1d-4c6f-9e2a-7d5b1c0a4e8f"`. |
| `prefix` | query | no | Return only secrets whose path starts with this prefix, such as `database/prod/`. Example: `"database/prod/"`. |
| `cursor` | query | no | The previous page's `nextCursor`. Omit it for the first page. Example: `"ZGF0YWJhc2UvcHJvZC9wYXNzd29yZA"`. |
| `limit` | query | no | The most secrets to return on one page, from 1 to 200. The default is 50. Example: `50`. |

## Responses

- **200**: A page of secrets.

| Field | Type | Required | Description |
|---|---|---|---|
| `nextCursor` | string \| null | no | Cursor for the next page; `null` when exhausted. Example: `"eyJuYW1lIjoiZGF0YWJhc2UvcHJvZC9wYXNzd29yZCJ9"`. |
| `secrets` | array of object | yes | The page's secrets: the caller's own and the ones shared with them. |
| `secrets.[]createdAt` | string (date-time) | yes | Creation timestamp. Example: `"2026-11-01T08:00:00.000Z"`. |
| `secrets.[]createdBy` | string | yes | Creating principal. Example: `"usr_7Hq2LmN9pR4s"`. |
| `secrets.[]id` | string | yes | `sec_<base62>`. Example: `"sec_4fK9xQ2mZ7aB"`. |
| `secrets.[]kid` | string | yes | KEK reference. Example: `"vkey_7Rt2Wq9LxP4m"`. |
| `secrets.[]metadata` | object | yes | Per-secret tags. Example: `{"team":"payments"}`. |
| `secrets.[]name` | string | yes | The secret's path. Example: `"database/prod/password"`. |
| `secrets.[]ownerId` | string | yes | The secret's owner. It never changes. Example: `"usr_7Hq2LmN9pR4s"`. |
| `secrets.[]retiredAt` | string (date-time) \| null | no | Retirement timestamp (or `null`). Example: `"2026-11-15T09:30:00.123Z"`. |
| `secrets.[]rotatedAt` | string (date-time) \| null | no | Last rotation timestamp (or `null`). Example: `"2026-11-15T09:30:00.123Z"`. |
| `secrets.[]updatedAt` | string (date-time) | yes | Last-update timestamp. Example: `"2026-11-15T09:30:00.123Z"`. |
| `secrets.[]updatedBy` | string | yes | Last-update principal. Example: `"usr_7Hq2LmN9pR4s"`. |
| `secrets.[]version` | integer (int64) | yes | Monotone version. Example: `3`. |
| `secrets.[]visibility` | object | yes | Who else can list and reveal a secret: `private` (the owner only, the default) or `shared` with the listed principals or roles. |
| _one of_ | | |  |
| `secrets.[]visibility.kind` | enum ("private") | yes |  |
| _or_ | | |  |
| `secrets.[]visibility.kind` | enum ("shared") | yes |  |
| `secrets.[]visibility.principals` | array of string | no | Subject ids granted read access (`usr_/svc_/ext_<base62>`). |
| `secrets.[]visibility.roles` | array of string | no | Roles granted read access (e.g. `["PROJECT_ADMIN"]` for a project-shared secret). |


## Errors

| HTTP | Description |
|---|---|
| 400 | `prefix` isn't a valid path prefix, or `cursor` isn't a cursor this list returned. |
| 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/secrets' \
  -H 'Authorization: Bearer $K9O_TOKEN'
```

### fetch

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

### k9o CLI

```bash
k9o vault-secret list
```

### @k9o/core

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


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