Secrets API
Secrets
POST /orgs/{org}/keys/rotate
Rotates the org's key-encryption key (admins).
Parameters
| Name | In | Type | Description |
|---|---|---|---|
org required | path | string | The org slug. |
Responses
200- OK. KekRotated
application/json
GET /orgs/{org}/secrets
Secret metadata you can see.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
org required | path | string | The org slug. |
space | query | string | Only this space (slug or id). |
Responses
200- OK. Paged_SecretMeta
application/json
POST /orgs/{org}/secrets
Stores a secret (space editors with org:secrets).
Parameters
| Name | In | Type | Description |
|---|---|---|---|
org required | path | string | The org slug. |
Request body
application/json, CreateSecret.
| Field | Type | Description |
|---|---|---|
kind required | string | Kind. |
meta | object | null | Metadata (no secret fields). |
name required | string | Name. |
require_confirmation | boolean | Reveals need a verified decision. |
space required | string | The space (slug or id). |
value required | object | The value: a JSON object with the kind's fields. |
Responses
201- Created. SecretMeta
application/json
GET /orgs/{org}/secrets/{ref}
A secret's metadata (space viewers).
Parameters
| Name | In | Type | Description |
|---|---|---|---|
org required | path | string | The org slug. |
ref required | path | string | The secret's short ID or UUID. |
Responses
200- OK. SecretMeta
application/json
PATCH /orgs/{org}/secrets/{ref}
Changes a secret's metadata, or its value (managers, or its creator).
Parameters
| Name | In | Type | Description |
|---|---|---|---|
org required | path | string | The org slug. |
ref required | path | string | The secret's short ID or UUID. |
Request body
application/json, UpdateSecret.
| Field | Type | Description |
|---|---|---|
meta | object | null | Metadata (replaces it). |
name | string | null | Name. |
require_confirmation | boolean | null | Reveals need a verified decision. |
value | object | null | A new value (a new version). |
Responses
200- OK. SecretMeta
application/json
DELETE /orgs/{org}/secrets/{ref}
Deletes a secret (its value is purged after the org's trash period).
Parameters
| Name | In | Type | Description |
|---|---|---|---|
org required | path | string | The org slug. |
ref required | path | string | The secret's short ID or UUID. |
Responses
204- No content
POST /orgs/{org}/secrets/{ref}/reveal
Reveals a value (§14.4). Agents need org:secrets, a task listing the secret, and a live, non-stale claim on it. Humans need a passkey step-up.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
org required | path | string | The org slug. |
ref required | path | string | The secret's short ID or UUID. |
Request body
application/json, RevealRequest.
| Field | Type | Description |
|---|---|---|
break_glass | boolean | Org owner only: reveal regardless of access, loudly logged. |
claim_id | string (uuid) | null | The agent's live claim on that task. |
reason | string | null | Why (required for break-glass). |
task | string | null | The task the secret is for (required for agents). |
Responses
200- OK. Revealed
application/json 403- Forbidden. ProblemBody
application/json
POST /orgs/{org}/secrets/{ref}/rotate
Replaces the value (a new version; the last 10 are kept).
Parameters
| Name | In | Type | Description |
|---|---|---|---|
org required | path | string | The org slug. |
ref required | path | string | The secret's short ID or UUID. |
Request body
application/json, RotateSecret.
| Field | Type | Description |
|---|---|---|
value required | object | The new value. |
Responses
200- OK. SecretMeta
application/json