Vault API

The Token Vault stores and proxies third-party OAuth tokens on behalf of users and agents. Agents retrieve fresh access tokens via a bearer-authenticated endpoint; admins manage providers and connections via the admin sub-tree.

Providers

Connections (user-facing)

Connections (admin)

Agent Token Retrieval

Returns a fresh access token for the authenticated user bound to the bearer token. The token must carry a user_id delegation binding.

Disconnect cascade (Layer 5)

Behavior

When an admin deletes a vault connection via DELETE /api/v1/admin/vault/connections/{id}, the server performs a cascade revocation of all OAuth tokens belonging to agents that have ever fetched a token from that vault connection.

The lookup is done by querying audit_logs for rows with action = 'vault.token.retrieved' and target_id = <connectionID>. Each distinct actor_id is resolved to an agent record; then all active OAuth tokens for that agent's client_id are soft-revoked (their revoked_at timestamp is set).

This ensures that if a vault connection is revoked, no agent can continue to exchange tokens on behalf of the revoked user account.

Response shape

{
  "disconnected": true,
  "connection_id": "vc_abc123",
  "revoked_agent_ids": ["agent_xyz", "agent_qrs"],
  "revoked_token_count": 4
}

Note: if no agent ever fetched from this connection, revoked_agent_ids is [] and revoked_token_count is 0. The response is still 200 OK.

Audit events emitted

Two audit events are written for every successful admin disconnect:

Both events have actor_type = "admin" and target_type = "vault_connection".

Query cascade events: