Authentication
The run, MCP and authoring routes take one Bearer credential: a personal API key. The authoring routes also accept a short-lived user access token (yku_…) minted from a signed-in browser session with POST /api/v1/auth/token; the partner namespace takes its own ykp_ key.
POST /api/public/v1/triggers/fire
POST /api/public/v1/agents/...
POST /api/public/v1/authoring/...
POST /api/public/v1/mcp
Authorization: Bearer yk_…
These routes answer at /api/public/v1; their former /api/v1 addresses keep working unchanged.
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.
Expiry, scopes and rotation
Every key has an expiry you chose. When you create one you pick how long it lives - 7, 30, 90, 180 or 365 days, 90 by default, never more than a year - or Never expires, for a system that must not stop on a date. Never expires has a cost: a leaked key keeps working until you revoke it. After its date a key stops working, exactly as if it had been revoked. You are emailed 14 days and 3 days before, and the API keys list flags a key that is about to end and marks every key that never expires. Keys created before expiry existed were given a date 90 days after this changed, with the same emails beforehand.
Each key does only what you choose. A key can be limited to any of:
| Choice | What it opens |
|---|---|
| Fire triggers | POST /api/public/v1/triggers/fire |
| Run agents | /api/public/v1/agents/... - start a conversation, read it, reply, approve, stream |
| MCP server | POST /api/public/v1/mcp |
| Build agents, integrations and knowledge | The authoring routes |
All four are ticked by default; untick what the system using the key does not need. A key used anywhere it was not allowed gets the same 404 as an unknown key. Narrowing never adds anything: the key still acts with its owner's permissions, and only within them.
Rotate (in the key's menu) replaces the secret and keeps the key's name and what it can do. The old secret stops working the moment you rotate, so update the systems that use it straight away. The new secret is shown once, with a fresh expiry choice.
Revoke stops a key at once and for good. The key stays listed under Show → Revoked keys, with its name, hint, and who revoked it and when, so you can still tell what a key used to be. A revoked key cannot be rotated or restored, and its name is free for a new key.
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 - including an expired key and a key not allowed at that route. 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.
The 404 from /triggers/fire does not say which part failed, but your workspace can see that calls are being refused. A trigger's page warns when fires were refused because the trigger was disabled or because the key's owner can no longer run it. Triggers → API keys shows calls from the last 7 days that never reached a trigger: a key that exists but can no longer be used, a request body that was not valid, or a trigger id that is not one of this workspace's API triggers. Only counts are kept, for 90 days - never the request itself or the key.
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.