Authentication & API keys

Each EVA API key belongs to exactly one workspace. Authenticate REST requests using:

Authorization: Bearer eva_v1_EXAMPLE_PREFIX.EXAMPLE_SECRET

The value above is illustrative. Send credentials only to EVA over HTTPS. API keys are server credentials, not browser configuration.

Manage keys in the dashboard

Open Developers → API Keys as a workspace administrator.

• Create: choose a name and permissions. The full secret is shown once.
• Inspect: view the prefix, permissions, creation date, last use, and revocation status.
• Rotate: create a replacement, update the application, verify it, then revoke the old key.
• Revoke: stop the key from authorizing further API requests.

Keys have no automatic expiry at present. Revoking a key does not cancel an already connected call or invalidate a previously issued, unexpired stream token. Stop active sessions separately when required.

Permissions

Scope	Allows
agents:read	Read agents, drafts, and published versions
agents:write	Create, edit, delete, and publish agents
conversations:read	Read call details, turns, events, and results
conversations:write	Create conversations
tools:read / tools:write	Read / manage tool definitions
usage:read	Read usage summaries
webhooks:read / webhooks:write	Read / manage webhook subscriptions
api_keys:read	List safe key metadata
api_keys:write	Issue and revoke workspace keys

The backend also has credential-management scopes for existing integrations. They are not part of the dashboard’s speech presets.

api_keys:write is a privileged permission: it can issue other keys with scopes beyond the issuing key’s own scopes. Do not grant it to an ordinary call integration. The Run calls preset excludes it.

Workspace selection

The key already identifies its workspace. You do not need an X-EVA-Organization-ID header for bearer requests. If you send one, it must match the key’s workspace. A key cannot select another tenant by changing that header.

Dashboard sessions use cookies and CSRF protection instead. A bearer header takes precedence over cookies; an invalid bearer key does not fall back to a signed-in session.

Key-management endpoints

Method	Path	Scope	Result
GET	/v1/api-keys	api_keys:read	Array of safe metadata
POST	/v1/api-keys	api_keys:write	201, metadata plus one-time api_key
DELETE	/v1/api-keys/{id}	api_keys:write	204, key revoked

Creation body:

{
  "name": "Production voice app",
  "scopes": ["agents:read", "conversations:read", "conversations:write"]
}

Metadata fields are id, name, prefix, scopes, created_at, last_used_at, and revoked_at. The two last timestamps may be null. Lists never return the secret or its stored hash.

Credential handling

Keep permanent keys and stream tokens out of source control, browser storage, analytics, and logs. Copy a newly created key into a secret manager or protected server environment. If the create response is lost, refresh the list and revoke the unwanted key before creating a replacement.