Authentication

Every route takes the same Bearer credential: a personal API key.

POST /api/v1/triggers/fire
POST /api/v1/agents/...
POST /api/v1/authoring/...
POST /api/v1/mcp
Authorization: Bearer yk_…

Personal keys are created under Triggers → API keys. The full key is displayed once at creation; only a hint remains visible afterward. Store it in a secret manager immediately.

A personal key acts with its owner's authority. The owner's current domain permission is checked on every call: Starting an Agent conversation requires domain execute permission. Reading an existing conversation requires session visibility; sending another message requires participation as its creator/recorded owner or a domain Operator, Editor or Owner. Agent authoring requires the same edit_automation or manage_knowledge permission as the corresponding console operation. Personal chats remain private to their creator, including from organization Owners/Admins. See Roles and permissions. The key does not become an independent service identity when the owner's access changes.

Permission failures

Trigger entry endpoints use 404 NOT_FOUND for missing-or-unauthorized failures. Agent conversation endpoints also return 404 for an invalid key or an unknown/cross-organization id, but a known resource can return 403 FORBIDDEN when domain or session visibility is missing. A visible session the key owner cannot participate in returns 403 SESSION_NOT_DRIVABLE. Authoring endpoints likewise return 403 for missing permissions on a known resource. Clients should preserve these distinct errors instead of treating every permission failure as a missing id.

Caller credentials are execution material, not the actor. On /triggers/fire, the personal API-key owner remains the recorded actor even when subscriber executions use supplied caller credentials.