Cortex API access is scoped to a workspace. Requests authenticate as a signed-in workspace member in the app or, for API-enabled workspaces, with a workspace credential issued by Cortex.
Header
For server-to-server API access, Cortex issues a bearer credential for the workspace:
Authorization: Bearer ctx_live_...
Browser requests from the Cortex app use the signed-in workspace session. Server integrations should use a dedicated Cortex-issued credential rather than a personal browser session. There is no self-service API-key screen in the app today.
Workspace scope
All API actions run inside one workspace. The authenticated identity must be a member of that workspace. Cortex re-checks membership and role on privileged actions, so removing a teammate or revoking access takes effect without relying on stale client-side state.
Write access
Actions that create uploads, build signatures, or start scorings require a writable workspace.
Writes can be blocked when:
- The user or credential is not a workspace member.
- The role is too low for the action.
- The trial has expired.
- The subscription is inactive.
- The workspace is read-only.
- Plan or usage limits have been reached.
Roles
Cortex uses workspace roles:
- Owner: manages billing and full workspace access.
- Admin: manages teammates and most workspace operations.
- Member: creates brands, references, signatures, uploads, and scorings when the workspace is writable.
Some settings and destructive operations require admin or owner access. Scoring and reference workflows are designed for regular workspace members.
Common auth errors
| Status | Code | Meaning |
|---|---|---|
| 401 | unauthenticated | No valid session or credential was provided. |
| 401 | not_a_member | The identity is not a member of the active workspace. |
| 401 | session_revoked | Access was revoked after the credential/session was issued. |
| 403 | no_workspace | Cortex could not resolve a workspace. |
| 403 | insufficient_role | The role is too low for the action. |
| 403 | workspace_read_only | The workspace cannot write because of billing, trial, or status. |
Credential safety
Keep API credentials in a server-side secret manager. Never ship them to a browser, mobile app, public repository, or client-side analytics tool.
Generated upload URLs are also temporary credentials. Treat them as sensitive while active and upload only the file they were created for.