# Request Reveal Challenge

`POST /vault/secrets/{path}?op=reveal-challenge` · Keys & Secrets · Secrets

Creates a secret at `path` from a base64 value, with a visibility and optional metadata. The creator owns it. The `op` query parameter selects another write on an existing secret instead: `move` gives it a new path, `rotate` re-seals its current value as a new version, and `reveal-challenge` returns a single-use challenge for Reveal Secret. Only the owner can move or rotate a secret.

## Parameters

| Name | In | Required | Description |
|---|---|---|---|
| `projectId` | query | yes | The project's id. Example: `"3f2c9a4e-8b1d-4c6f-9e2a-7d5b1c0a4e8f"`. |
| `path` | path | yes | The secret's path: `/`-delimited segments, such as `database/prod/password`. Example: `"database/prod/password"`. |

## Request body

| Field | Type | Required | Description |
|---|---|---|---|
| _one of_ | | |  |
| `metadata` | object | no | Optional per-secret tags. Example: `{"team":"payments"}`. |
| `value` | string | yes | The secret's value, base64. Kibo encrypts it before it is stored. Example: `"czNjcjN0LXBhc3N3MHJk"`. |
| `visibility` | object | no | Who else can list and reveal a secret: `private` (the owner only, the default) or `shared` with the listed principals or roles. |
| _one of_ | | |  |
| `visibility.kind` | enum ("private") | yes |  |
| _or_ | | |  |
| `visibility.kind` | enum ("shared") | yes |  |
| `visibility.principals` | array of string | no | Subject ids granted read access (`usr_/svc_/ext_<base62>`). |
| `visibility.roles` | array of string | no | Roles granted read access (e.g. `["PROJECT_ADMIN"]` for a project-shared secret). |
| _or_ | | |  |
| `newPath` | string | yes | The new `/`-delimited path. Example: `"database/staging/password"`. |

```json
{
  "value": "czNjcjN0LXBhc3N3MHJk",
  "visibility": {
    "kind": "private"
  },
  "metadata": {
    "team": "payments"
  }
}
```

## Responses

- **200**: `op=move`: the secret at its new path. `op=rotate`: its new version. `op=reveal-challenge`: the challenge.

| Field | Type | Required | Description |
|---|---|---|---|
| _one of_ | | |  |
| `event` | string | yes | The ledger event recorded for the move. Example: `"SECRET_PATH_CHANGED"`. |
| `id` | string | yes | `sec_<base62>`, unchanged by the move. Example: `"sec_4fK9xQ2mZ7"`. |
| `name` | string | yes | The new path-name. Example: `"database/staging/password"`. |
| _or_ | | |  |
| `id` | string | yes | `sec_<base62>`. Example: `"sec_4fK9xQ2mZ7"`. |
| `ledgerSequenceNumber` | integer (int64) | yes | The `SECRET_KEY_ROTATED` entry's place in the project's signed ledger. Example: `1842`. |
| `name` | string | yes | The secret's path. Example: `"database/prod/password"`. |
| `rotatedAt` | string (date-time) | yes | When the rotation was sealed. Example: `"2026-11-15T09:30:00.123Z"`. |
| `version` | integer (int64) | yes | The new version, one above the previous. Example: `4`. |
| _or_ | | |  |
| `challenge` | string | yes | `rvc_<base62>` single-use challenge token. Example: `"rvc_9TqLm2Xa7Pz4"`. |
| `expiresAt` | string (date-time) | yes | Expiry (default +60s). Example: `"2026-11-15T09:31:00.123Z"`. |

- **201**: The secret was created.

| Field | Type | Required | Description |
|---|---|---|---|
| `createdAt` | string (date-time) | yes | Creation timestamp. Example: `"2026-11-01T08:00:00.000Z"`. |
| `createdBy` | string | yes | Creating principal. Example: `"usr_7Hq2LmN9pR4s"`. |
| `id` | string | yes | `sec_<base62>`. Example: `"sec_4fK9xQ2mZ7aB"`. |
| `kid` | string | yes | KEK reference. Example: `"vkey_7Rt2Wq9LxP4m"`. |
| `metadata` | object | yes | Per-secret tags. Example: `{"team":"payments"}`. |
| `name` | string | yes | The secret's path. Example: `"database/prod/password"`. |
| `ownerId` | string | yes | The secret's owner. It never changes. Example: `"usr_7Hq2LmN9pR4s"`. |
| `retiredAt` | string (date-time) \| null | no | Retirement timestamp (or `null`). Example: `"2026-11-15T09:30:00.123Z"`. |
| `rotatedAt` | string (date-time) \| null | no | Last rotation timestamp (or `null`). Example: `"2026-11-15T09:30:00.123Z"`. |
| `updatedAt` | string (date-time) | yes | Last-update timestamp. Example: `"2026-11-15T09:30:00.123Z"`. |
| `updatedBy` | string | yes | Last-update principal. Example: `"usr_7Hq2LmN9pR4s"`. |
| `version` | integer (int64) | yes | Monotone version. Example: `3`. |
| `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_ | | |  |
| `visibility.kind` | enum ("private") | yes |  |
| _or_ | | |  |
| `visibility.kind` | enum ("shared") | yes |  |
| `visibility.principals` | array of string | no | Subject ids granted read access (`usr_/svc_/ext_<base62>`). |
| `visibility.roles` | array of string | no | Roles granted read access (e.g. `["PROJECT_ADMIN"]` for a project-shared secret). |


## Errors

| HTTP | Description |
|---|---|
| 400 | The path or the body isn't valid. |
| 401 | The request carries no authenticated caller. |
| 403 | The caller can see the secret but doesn't own it. |
| 404 | No such secret visible to the caller. |
| 409 | `K9O_SECRET_ALREADY_EXISTS`: a secret already exists at the path (a create, or a move's new path). `K9O_REKEY_IN_PROGRESS` or `K9O_CUSTODY_TRANSITION_IN_PROGRESS`: a key rotation or custody change is running, so a create or rotate waits. Retry when it completes. |

## Code samples

### cURL

```bash
curl -X POST 'https://<org>.api-<region>.k9o.io/@storefront/vault/secrets/<name>?op=reveal-challenge' \
  -H 'Authorization: Bearer $K9O_TOKEN'
```

### fetch

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

### k9o CLI

```bash
k9o vault-secret reveal <name> --region <region>
```

### @k9o/core

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


Canonical page: https://docs.kilimanjaro.dev/api-playground/keys-secrets/request-reveal-challenge
