/vault/secrets/{path}?op=rotateRotate Secret
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.
| projectId * | query | The project's id. |
| path * | path | The secret's path: |
| One of: object | ||
| metadata | object | Optional per-secret tags. |
| value * | string | The secret's value, base64. Kibo encrypts it before it is stored. Example: "czNjcjN0LXBhc3N3MHJk" |
| visibility | any | Who else can list and reveal a secret: |
| One of: object | ||
| kind * | "private" | |
| or: object | ||
| kind * | "shared" | |
| principals | string[] | Subject ids granted read access ( |
| roles | string[] | Roles granted read access (e.g. |
| or: object | ||
| newPath * | string | The new Example: "database/staging/password" |
| HTTP | K9O Code | Description |
|---|---|---|
| 200 | `op=move`: the secret at its new path. `op=rotate`: its new version. `op=reveal-challenge`: the challenge. | |
| 201 | The secret was created. | |
| 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. |
| One of: object | ||
| event * | string | The ledger event recorded for the move. Example: "SECRET_PATH_CHANGED" |
| id * | string |
Example: "sec_4fK9xQ2mZ7" |
| name * | string | The new path-name. Example: "database/staging/password" |
| or: object | ||
| id * | string |
Example: "sec_4fK9xQ2mZ7" |
| ledgerSequenceNumber * | integer <int64> | The Example: 1842 |
| name * | string | The secret's path. Example: "database/prod/password" |
| rotatedAt * | string <date-time> | When the rotation was sealed. Example: "2026-11-15T09:30:00.123Z" |
| version * | integer <int64> | The new version, one above the previous. Example: 4 |
| or: object | ||
| challenge * | string |
Example: "rvc_9TqLm2Xa7Pz4" |
| expiresAt * | string <date-time> | Expiry (default +60s). Example: "2026-11-15T09:31:00.123Z" |
| createdAt * | string <date-time> | Creation timestamp. Example: "2026-11-01T08:00:00.000Z" |
| createdBy * | string | Creating principal. Example: "usr_7Hq2LmN9pR4s" |
| id * | string |
Example: "sec_4fK9xQ2mZ7aB" |
| kid * | string | KEK reference. Example: "vkey_7Rt2Wq9LxP4m" |
| metadata * | object | Per-secret tags. |
| name * | string | The secret's path. Example: "database/prod/password" |
| ownerId * | string | The secret's owner. It never changes. Example: "usr_7Hq2LmN9pR4s" |
| retiredAt | string <date-time> | null | Retirement timestamp (or Example: "2026-11-15T09:30:00.123Z" |
| rotatedAt | string <date-time> | null | Last rotation timestamp (or Example: "2026-11-15T09:30:00.123Z" |
| updatedAt * | string <date-time> | Last-update timestamp. Example: "2026-11-15T09:30:00.123Z" |
| updatedBy * | string | Last-update principal. Example: "usr_7Hq2LmN9pR4s" |
| version * | integer <int64> | Monotone version. Example: 3 |
| visibility * | any | Who else can list and reveal a secret: |
| One of: object | ||
| kind * | "private" | |
| or: object | ||
| kind * | "shared" | |
| principals | string[] | Subject ids granted read access ( |
| roles | string[] | Roles granted read access (e.g. |
// const k9o = new K9o({ orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…' })
const { data } = await k9o.kibo.vault.secrets.rotate('<name>')Showing example in TypeScript
{
"value": "czNjcjN0LXBhc3N3MHJk",
"visibility": {
"kind": "private"
},
"metadata": {
"team": "payments"
}
}{
"event": "SECRET_PATH_CHANGED",
"id": "sec_4fK9xQ2mZ7",
"name": "database/staging/password"
}{
"createdAt": "2026-11-01T08:00:00.000Z",
"createdBy": "usr_7Hq2LmN9pR4s",
"id": "sec_4fK9xQ2mZ7aB",
"kid": "vkey_7Rt2Wq9LxP4m",
"metadata": {
"team": "payments"
},
"name": "database/prod/password",
"ownerId": "usr_7Hq2LmN9pR4s",
"retiredAt": "2026-11-15T09:30:00.123Z",
"rotatedAt": "2026-11-15T09:30:00.123Z",
"updatedAt": "2026-11-15T09:30:00.123Z",
"updatedBy": "usr_7Hq2LmN9pR4s",
"version": 3,
"visibility": {
"kind": "private"
}
}