> ## Documentation Index
> Fetch the complete documentation index at: https://docs.steward.fi/llms.txt
> Use this file to discover all available pages before exploring further.

# Secrets

> Create, rotate, and manage encrypted API credentials.

# 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:**

```typescript theme={null}
{
  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):**

```json theme={null}
{
  "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

```bash theme={null}
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:**

```json theme={null}
{
  "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:**

```typescript theme={null}
{
  value: string; // New credential value
}
```

***

## Delete Secret

Soft-deletes a secret.

```
DELETE /secrets/:id
```

**Auth:** Tenant API key

**Response:**

```json theme={null}
{
  "ok": true,
  "data": { "deleted": "550e8400-..." }
}
```

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

***

## 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:**

```typescript theme={null}
{
  value: string; // New credential value
}
```

**Response:**

```json theme={null}
{
  "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

```bash theme={null}
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..." }'
```