Skip to content
ExoVault

Search Documentation

Search across all documentation pages

Authentication

ExoVault uses agent keys for API authentication. Agent keys are tied to an integration (agent configuration) and scoped to specific vaults with granular permission levels.

Agent Keys#

Agent keys are opaque tokens with the exv_ prefix. They are generated from the dashboard when creating or managing an integration.

exv_abc123def456...

How to Use#

Include the key as a Bearer token in the Authorization header:

http
Authorization: Bearer exv_your_agent_key_here

Key Properties#

PropertyDescription
keyHashSHA-256 hash stored server-side. The raw key is never stored.
integrationIdLinks the key to an agent integration configuration.
userIdThe user who owns the key.
vaultIdOptional legacy single-vault restriction.
expiresAtOptional expiration timestamp.
isRevokedWhether the key has been manually revoked.
lastUsedAtAutomatically updated on each request.

Key Lifecycle#

  1. Creation -- Generated in the dashboard under Settings > Agent Keys
  2. Usage -- lastUsedAt is updated on every request (fire-and-forget, non-blocking)
  3. Revocation -- Can be revoked from the dashboard at any time
  4. Expiration -- Keys with an expiresAt date are rejected after that time

Scope Presets#

Each integration has a scope preset that determines what operations the agent can perform. Scopes are derived from the integration's current preset (not frozen at key creation time), so changes take effect immediately.

PresetScopesDescription
read_onlyread, searchCan read memories, notes, and search. Cannot write.
read_writeread, write, searchFull read/write access. Most common.
adminread, write, search, adminFull access including admin operations.

Scope Enforcement#

Each route checks for the required scope before executing:

  • read -- Required for session-start, read-memories, search-memories, read-note, list-*, etc.
  • write -- Required for write-memory, create-note, update-*, send-message, ingest-turn, etc.
  • search -- Required for search-memories, semantic-search, search-notes, etc.
  • admin -- Required for administrative operations like managing settings.

If the agent lacks the required scope, the API returns:

json
{
  "error": "SCOPE_DENIED: This key does not have 'write' permission"
}

Status code: 403

Vault Restrictions#

Integrations can be configured as restricted or unrestricted:

Unrestricted Access#

When restrictToVault is false, the agent can access all vaults owned by the user. The vaultId in requests is optional and defaults to the integration's primary vault.

Restricted Access (Multi-Vault)#

When restrictToVault is true, the agent can only access vaults explicitly granted via the agent_vault_access junction table. Attempting to access an unauthorized vault returns:

json
{
  "error": "SCOPE_DENIED: This key does not have access to the requested vault"
}

Per-Vault Scope Overrides#

Each vault in the access list can have its own scope preset override. This enables scenarios like:

  • Read-write access to vault-A, read-only access to vault-B
  • Admin access to a personal vault, read-only to a shared team vault

When a per-vault override exists, it takes full precedence over the integration-level preset for operations in that vault. Per-vault overrides can be more or less permissive than the global default.

Vault Resolution#

When a request includes a vaultId field, the API resolves the effective vault through this logic:

  1. If the agent is unrestricted: uses the requested vaultId, or falls back to the integration's default vault.
  2. If the agent is restricted: validates the requested vault is in allowedVaultIds. If no vault is requested, falls back to the primary vault or the first allowed vault.

Wrapped MEK (Encryption Keys)#

Each integration stores a wrapped Master Encryption Key (MEK) that enables the server to encrypt and decrypt content on behalf of the agent. Without this, operations requiring encryption will fail:

json
{
  "error": "Integration encryption is not configured. Re-create the integration from the dashboard."
}

Status code: 403

The MEK is wrapped (encrypted) with the server's key and can only be unwrapped for the specific user. This is part of ExoVault's zero-knowledge architecture. See Encryption for details.

Auth Info Endpoint#

To inspect the current key's permissions, use the info endpoint:

http
GET /api/agent/info
Authorization: Bearer exv_your_key

Response:

json
{
  "userId": "...",
  "integrationId": "...",
  "agentType": "claude_code",
  "label": "Claude Code",
  "scopes": ["read", "write", "search"],
  "vaultId": "...",
  "allowedVaultIds": ["vault-a", "vault-b"],
  "restrictToVault": true,
  "vaultScopePresets": {
    "vault-a": "read_write",
    "vault-b": "read_only"
  }
}