Secrets
The secrets API provides an encrypted key-value store for API keys, tokens, and other sensitive values. Values are encrypted at rest using AES-256 and are never returned in list responses.
Secret values are encrypted before being written to the database. The encryption key is derived from your application's configuration. Only the GET /api/secrets/:key endpoint decrypts and returns the actual value.
Endpoints
List Secrets
GET /api/secrets
List all stored secrets. Returns metadata only -- values are never included.
Authentication: Required
Response: 200 OK
{
"data": [
{
"id": "uuid",
"key": "OPENAI_API_KEY",
"description": "OpenAI API key for embeddings",
"createdAt": "2026-02-15T10:00:00.000Z",
"updatedAt": "2026-02-18T08:00:00.000Z"
}
]
}
Create Secret
POST /api/secrets
Store a new encrypted secret. Keys must be in SCREAMING_SNAKE_CASE format and unique.
Authentication: Required
Request Body:
| Field | Type | Required | Description |
|---|---|---|---|
key | string | Yes | Unique key in SCREAMING_SNAKE_CASE (max 255 chars) |
value | string | Yes | Secret value (encrypted before storage) |
description | string | No | Human-readable description |
Response: 201 Created
{
"data": {
"id": "uuid",
"key": "GITHUB_TOKEN",
"description": "GitHub personal access token",
"createdAt": "2026-02-18T12:00:00.000Z"
}
}
Errors:
| Status | Condition |
|---|---|
400 | Missing key or value, or invalid key format |
409 | Key already exists |
Key format must match /^[A-Z][A-Z0-9_]*$/ -- start with an uppercase letter, followed by uppercase letters, digits, or underscores. Examples: MY_API_KEY, GITHUB_TOKEN, S3_SECRET.
Get Secret Value
GET /api/secrets/:key
Retrieve and decrypt a secret value by its key.
Authentication: Required
Path Parameters:
| Param | Type | Description |
|---|---|---|
key | string | The secret key (e.g., GITHUB_TOKEN) |
Response: 200 OK
{
"data": {
"key": "GITHUB_TOKEN",
"value": "ghp_xxxxxxxxxxxxxxxxxxxx"
}
}
Errors:
| Status | Condition |
|---|---|
400 | Missing key |
404 | Secret not found |
Update Secret
PUT /api/secrets/:key
Update the value and/or description of an existing secret. Broadcasts a resource_change notification.
Authentication: Required
Path Parameters:
| Param | Type | Description |
|---|---|---|
key | string | The secret key |
Request Body:
| Field | Type | Required | Description |
|---|---|---|---|
value | string | No | New secret value (re-encrypted) |
description | string | No | Updated description |
Response: 200 OK
{
"data": {
"id": "uuid",
"key": "GITHUB_TOKEN",
"description": "Updated GitHub token",
"updatedAt": "2026-02-18T14:00:00.000Z"
}
}
Errors:
| Status | Condition |
|---|---|
400 | Missing key |
404 | Secret not found |
Delete Secret
DELETE /api/secrets/:key
Permanently delete a secret. Broadcasts a resource_change notification.
Authentication: Required
Path Parameters:
| Param | Type | Description |
|---|---|---|
key | string | The secret key |
Response: 200 OK
{ "data": { "deleted": true } }
Errors:
| Status | Condition |
|---|---|
400 | Missing key |
404 | Secret not found |