Vault API

The vault is a centralized secret store. Secrets are stored as references and access is controlled through a grant system -- agents must be explicitly granted access to specific secrets.

Create Secret

POST /v1/vault/secrets

Creates a new secret reference in the vault.

Request

{
  "name": "OPENAI_API_KEY",
  "value": "sk-xxxxxxxxxxxx"
}

Response (201)

{
  "id": "sec_abc123",
  "name": "OPENAI_API_KEY",
  "created_at": "2025-03-15T10:00:00Z"
}

Secret values are encrypted at rest and never returned in API responses after creation.

List Secrets

GET /v1/vault/secrets

Returns metadata for all secret references. Values are never included.

Response (200)

[
  {
    "id": "sec_abc123",
    "name": "OPENAI_API_KEY",
    "created_at": "2025-03-15T10:00:00Z"
  },
  {
    "id": "sec_def456",
    "name": "TELEGRAM_BOT_TOKEN",
    "created_at": "2025-03-15T11:00:00Z"
  }
]

Delete Secret

DELETE /v1/vault/secrets/{id}

Deletes a secret and all associated grants.

Example

curl -X DELETE http://127.0.0.1:3000/v1/vault/secrets/sec_abc123

Response (204)

No content.

Grant Agent Access

POST /v1/vault/grants

Grants an agent access to a specific secret. Without a grant, the agent cannot read the secret even if it exists in the vault.

Request

{
  "agent_id": "researcher",
  "secret_id": "sec_abc123"
}

Response (201)

{
  "grant_id": "grt_xyz789",
  "agent_id": "researcher",
  "secret_id": "sec_abc123",
  "created_at": "2025-03-15T12:00:00Z"
}

Access Model

The vault uses a grant-based access model:

1. Secrets are centralized -- all secrets live in a single vault, not per-agent.
2. Access requires an explicit grant -- an agent can only read a secret if a grant exists linking the agent to that secret.
3. Agents access secrets via primitives -- during a run, the agent uses the vault.read primitive to retrieve a secret value. The system checks for a valid grant before returning the value.
4. Access is audited -- every secret access (and denial) emits vault.accessed or vault.denied events in the SSE stream.

How Agents Use Secrets

Agents do not call the vault API directly. Instead, they use the vault.read primitive during runs:

vault.read("OPENAI_API_KEY")

If the agent has a valid grant for that secret, the value is returned to the agent's context. If not, a vault.denied event is emitted and the agent receives an error.

Security Notes

1. Encryption at rest -- Secret values are encrypted before storage
2. No value exposure -- API list and detail endpoints never return secret values
3. Grant isolation -- Each agent only sees secrets it has been explicitly granted
4. Audit trail -- All vault operations generate audit events
5. SHA-256 references -- Secret references are hashed for safe indexing