Secrets API

Manage encrypted credentials in the Secret Vault. All endpoints require tenant-level authentication. Secret values are never returned in responses.

Create Secret

POST /secrets

Auth: Tenant API key Request Body:

{
  name: string;          // Unique name within tenant (e.g., "openai-prod")
  value: string;         // The credential value (encrypted at rest)
  description?: string;  // Human-readable description
  expiresAt?: string;    // ISO 8601 expiry date
}

Response (201):

{
  "ok": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "openai-prod",
    "description": "Production OpenAI API key",
    "version": 1,
    "expiresAt": "2027-01-01T00:00:00Z",
    "createdAt": "2026-03-26T12:00:00Z"
  }
}

Errors:

409 — Secret with this name already exists

curl -X POST http://localhost:3200/secrets \
  -H "X-Steward-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "openai-prod",
    "value": "sk-proj-abc123...",
    "description": "Production OpenAI API key"
  }'

List Secrets

Returns metadata for all secrets in the tenant. Values are never included.

GET /secrets

Auth: Tenant API key Response:

{
  "ok": true,
  "data": [
    {
      "id": "550e8400-...",
      "name": "openai-prod",
      "description": "Production OpenAI API key",
      "version": 1,
      "createdAt": "2026-03-26T12:00:00Z"
    },
    {
      "id": "660f9500-...",
      "name": "anthropic-prod",
      "version": 2,
      "createdAt": "2026-03-20T10:00:00Z"
    }
  ]
}

Get Secret

Returns metadata for a single secret.

GET /secrets/:id

Auth: Tenant API key

Update Secret

Updates the secret value, creating a new encrypted version.

PUT /secrets/:id

Auth: Tenant API key Request Body:

{
  value: string; // New credential value
}

Delete Secret

Soft-deletes a secret.

DELETE /secrets/:id

Auth: Tenant API key Response:

{
  "ok": true,
  "data": { "deleted": "550e8400-..." }
}

Deleting a secret will cause any routes referencing it to fail. Ensure no active routes depend on the secret before deletion.

Rotate Secret

Creates a new version of the secret with a new value. Routes automatically use the latest version.

POST /secrets/:id/rotate

Auth: Tenant API key Request Body:

{
  value: string; // New credential value
}

Response:

{
  "ok": true,
  "data": {
    "id": "550e8400-...",
    "name": "openai-prod",
    "version": 2,
    "rotatedAt": "2026-03-27T10:00:00Z"
  }
}

Key benefits of rotation:

Zero downtime — routes use the latest version automatically
No redeployment — agent containers don’t change
Audit trail — rotation events are logged

curl -X POST http://localhost:3200/secrets/550e8400-.../rotate \
  -H "X-Steward-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{ "value": "sk-proj-new-key-xyz..." }'

​Secrets API

​Create Secret

​List Secrets

​Get Secret

​Update Secret

​Delete Secret

​Rotate Secret

Secrets API

Create Secret

List Secrets

Get Secret

Update Secret

Delete Secret

Rotate Secret