Secret Vault Endpoints

Store and retrieve encrypted secrets — API keys, connection strings, and other sensitive values.

Store Secret

POST /api/v1/secrets

Headers

• Authorization: Bearer <apiKey>
• X-Bulwark-Tenant: <tenant-id>

Body

{
  "name": "stripe-secret-key",
  "value": "sk_live_...",
  "description": "Stripe production secret key",
  "tags": ["payment", "production"],
  "accessPolicy": {
    "agents": ["agent_01j..."],
    "scopes": ["secrets:stripe"]
  }
}

Response 201

{
  "data": {
    "secretId": "sec_01j...",
    "name": "stripe-secret-key",
    "description": "Stripe production secret key",
    "tags": ["payment", "production"],
    "createdAt": "2026-03-18T00:00:00Z"
  }
}

The secret value is never returned after creation.

Get Secret Value

GET /api/v1/secrets/{secretId}/value

Returns the decrypted secret value. Requires explicit secrets:read scope. Every access is logged.

Response 200

{
  "data": {
    "secretId": "sec_01j...",
    "name": "stripe-secret-key",
    "value": "sk_live_...",
    "accessedAt": "2026-03-18T13:00:00Z"
  }
}

List Secrets

GET /api/v1/secrets

Returns metadata only — never values.

Response 200

{
  "data": [
    {
      "secretId": "sec_01j...",
      "name": "stripe-secret-key",
      "description": "Stripe production secret key",
      "tags": ["payment", "production"],
      "lastAccessedAt": "2026-03-18T13:00:00Z",
      "createdAt": "2026-03-18T00:00:00Z"
    }
  ]
}

Update Secret

PUT /api/v1/secrets/{secretId}

Rotate the secret value. The old value is immediately invalidated.

Body

{
  "value": "sk_live_new_..."
}

Response 200

{
  "data": {
    "secretId": "sec_01j...",
    "name": "stripe-secret-key",
    "updatedAt": "2026-03-18T14:00:00Z",
    "version": 2
  }
}

Delete Secret

DELETE /api/v1/secrets/{secretId}

Permanently deletes the secret. This action cannot be undone.

Response 200

{
  "data": {
    "secretId": "sec_01j...",
    "deletedAt": "2026-03-18T14:00:00Z"
  }
}