Skip to main content

​
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 https://api.steward.fi/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 https://api.steward.fi/secrets/550e8400-.../rotate \
  -H "X-Steward-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{ "value": "sk-proj-new-key-xyz..." }'