Authentication

The Evose API uses Bearer Token authentication. Tokens come from organization-level API Keys.

Create an API Key

[Org management · API Management] → New API Key:

Field	Description
Name	Note the use (e.g. `marketing-prod-key`)
Scopes	Restrict accessible resource types
Workspace restriction	Specific workspaces only (optional)
Expiration	Auto-expire (optional)
IP allowlist	Allowed IPs only (optional)

Key shown once

After creation, the full key is shown only at the moment of creation; once you close the dialog it cannot be viewed again. Save it immediately.

Each request carries the Authorization header:

Authorization: Bearer evk_xxxxxxxxxxxxxxxxx

Scope	Includes
`read`	List / read resources
`agent:invoke`	Invoke Agents
`workflow:invoke`	Trigger Workflows
`knowledge:read`	Search knowledge bases
`knowledge:write`	Upload / delete documents
`admin`	Manage resources (create / modify / delete)
`*`	All (use with care)

Least privilege

Grant business-system keys only the necessary scopes. Backend invoking Agents → grant only agent:invoke.

Some scenarios need direct front-end calls (such as the JS SDK) — use a public key:

Authorization: Bearer pub_xxxxxxxxxxxxxxxxx

Public keys:

Calls must indicate the end user (for audit, attribution, ACL checks):

{
  "message": "...",
  "user_id": "u-internal-id",
  "user_name": "Alice",
  "user_email": "alice@example.com"
}

Action	Behavior
Create new key	Immediately usable
Mark old key deprecated	Still works; UI shows red warning
Revoke old key	Immediately invalidated

Recommended rotation: 90 days. Strict compliance: 30 days.