Authentication

Cortex supports three authentication methods. All protected endpoints require at least one.

1. JWT Bearer Token

The primary authentication method. Tokens are HS256-signed JWTs with 30-day expiry.

Obtain a Token

curl -X POST https://api.cortex.acrobi.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "yourpassword"}'

Response:

{
  "user": { "id": "user-123", "email": "user@example.com", "name": "Alice", "role": "user" },
  "token": "eyJ...",
  "refreshToken": "eyJ..."
}

Use the Token

Authorization: Bearer eyJ...

Refresh Before Expiry

curl -X POST https://api.cortex.acrobi.com/api/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refreshToken": "eyJ..."}'

2. API Key

For external integrations (MCP servers, automation, CI/CD). API keys use the sk-ctx- prefix and are SHA-256 hashed for storage.

X-API-Key: sk-ctx-abc123...

API keys support scoped access:

• read — Read-only access
• write — Read + write access
• admin — Full administrative access

Generate API keys via POST /api/settings/api-key/regenerate or in the dashboard under Settings.

3. Scope Headers

Many endpoints are scope-aware. Include these headers to target a specific workspace or project:

Header	Description	Example
X-Organization-Id	Target organization/workspace	org-abc123
X-Project-Id	Target project within org	proj-def456
x-scope-type	Scope type identifier	organization or project

Agent Identity Headers

When operating as an AI agent, include these additional headers for tracking and audit:

Header	Description	Example
X-Agent-Definition	Agent type name	coder-agent
X-Agent-Instance-Id	Unique instance identifier	inst-789xyz
X-Agent-Display-Name	Human-readable name	Backend Coder #3
X-Agent-Owner-Id	User who owns this agent	user-123

Rate Limiting

All endpoints enforce rate limiting by user and tier. Response headers indicate current state:

Header	Description
X-RateLimit-Limit	Maximum requests per window
X-RateLimit-Remaining	Requests remaining in window
X-RateLimit-Reset	UTC timestamp when window resets
Retry-After	Seconds to wait (only on 429 responses)

RBAC Roles

Role	Level	Description
superadmin	100	Full platform access
admin	80	Organization-level admin
manager	60	Team management
member	40	Standard user
guest	20	Read-only access

Role level determines which capabilities an agent or user can access. See Capabilities for the full matrix.