API authentication

Operade uses two primary credential types: API keys for reviewed customer API operations and a browser session cookie for dashboard operations. An operation page states which form is accepted and the minimum role.

API keys#

Send a key as Authorization: Bearer YOUR_API_KEY. A key belongs to one Workspace and acts with workspace-admin authorization on routes that explicitly allow API keys. This means the key can access all resources exposed by an allowed operation inside that Workspace, including another member's private resource when that operation has creator or sharing filters for human members. Keys do not currently have configurable per-key roles or resource allowlists.

Invalid and revoked keys return HTTP 401. A valid key does not fall back to a browser cookie and cannot call dashboard-only routes, create more keys, revoke keys, or manage Secret values. Workspace-admin authorization on allowed routes does not turn the key into an owner dashboard session.

Keys are shown once at creation. Store them in an approved secret manager, never in source control, browser code, logs, or public examples. Revoke a compromised key in the dashboard and issue a replacement; the old value cannot be recovered.

Dashboard sessions#

The dashboard uses the cx_session cookie. It is set with HttpOnly, Secure, SameSite=Lax, and path /. Routes then enforce Workspace membership and the minimum owner, admin, or member role. Sending a Bearer header to a session-only route is rejected rather than treated as a session request.

For a cookie-authenticated POST, PUT, PATCH, or DELETE, send X-CX-Request: 1. This request-intent check protects browser mutations. It is not required for a pure API-key request because browsers do not attach an API key automatically.

Credential matrix#

• Customer API with API-key support: Bearer API key, no CSRF header, workspace-admin authorization inside the key's Workspace, limited to reviewed API-key routes.
• Dashboard session API: cx_session cookie, plus X-CX-Request: 1 for mutations, scoped to the user's Workspace role.
• Public login and logout behavior: no credential is required; logout revokes an existing server session, and request-intent applies when its cookie is present.
• Provider callback: provider-specific secret header, no session or API key, scoped to the configured provider channel.

Telegram callbacks use X-Telegram-Bot-Api-Secret-Token. A missing or invalid callback secret can receive a quiet HTTP 200 response without processing so the receiver does not reveal channel state or amplify provider retries.

Login and logout#

Authentication routes document their own anonymous behavior. POST /api/v1/auth/logout does not require authentication: an anonymous caller receives HTTP 204, and the server revokes the session when a valid cookie is present. The current 204 response does not guarantee that the client cookie is cleared. A non-browser or API client should discard the cookie from its cookie jar after HTTP 204. Browser JavaScript cannot remove the HttpOnly cookie; a browser user should sign in again so the cookie is replaced, or clear site data or cookies through browser settings before the next sign-in. When a session cookie is present on the mutation, the normal browser request-intent check still applies.

Failure handling#

HTTP 401 means the credential is missing, expired, invalid, or revoked. HTTP 403 means a known identity, role, or credential type cannot perform the action. HTTP 404 can deliberately hide a resource outside the credential's Workspace. Do not probe other Workspace identifiers to diagnose access.

For examples and recovery, see Workspace API keys, Authentication troubleshooting, and Resource scope.