Authentication

How agent keys work in Cortex.

Every MCP request must authenticate with an agent key. Keys are created in the Cortex dashboard and are shown once.

Agent Keys

Agent keys look like:

crtx_a1b2c3d4e5f6g7h8i9j0

Each key is:

Bound to an acting user (the human the agent represents)
Scoped to the agent's permissions
Hashed before storage (never stored in plaintext)

Creating an Agent Key

Navigate to Gateway & Agents in the Cortex dashboard
Click Connect agent
Select the acting user and agent surface (Claude Code, Cursor, CLI, etc.)
Copy the key immediately — it's shown only once

If you skipped CLI/MCP setup during onboarding, Gateway & Agents is where to finish it — it has the same setup steps (install commands, paste-a-prompt, manual config) as onboarding, plus every key your org has issued. One agent key authenticates both the CLI and the MCP server; a key created for either surface works for both.

Revoking a Key

Revoking is immediate and irreversible — the key stops authenticating on its very next request; there is no grace period, and there is no "un-revoke." A new key must be issued to reconnect.

Who can revoke a given agent's key:

Caller	Can revoke
The agent's own user	Their own agents
A Manager	Agents belonging to their direct reports
The CEO	Any agent in the org

This is enforced server-side (not just hidden in the UI), so a Manager's revoke request for someone outside their reporting line is rejected with 403.

Key Verification

When a request arrives, the gateway:

Extracts the key from Authorization: Bearer crtx_... or x-cortex-agent-key
Hashes the key
Looks up the agent in the agents table
Loads the acting user's identity (role, level, org)
Binds all subsequent tool calls to that identity

sequenceDiagram
    participant Agent
    participant Gateway as MCP Gateway
    participant DB as Database

    Agent->>Gateway: POST /mcp (with crtx_... key)
    Gateway->>Gateway: Hash key
    Gateway->>DB: SELECT agent WHERE api_key_hash = ?
    DB-->>Gateway: Agent + acting_user
    Gateway->>Gateway: Build per-agent server
    Gateway->>Gateway: Execute tool as acting_user
    Gateway-->>Agent: JSON-RPC response

Environment Variables

You can also pass keys via environment variables:

export CORTEX_API_KEY="crtx_YOUR_KEY_HERE"
export CORTEX_URL="https://your-cortex-host"

Security Properties

Property	Description
No write-up leaks	An agent can only write into scopes its user can read
Deny beats allow	If a role has conflicting policies, deny wins
Audit trail	Every key usage is logged with actor, action, and result
One-time display	Keys are shown once at creation — recover by regenerating