Authentication

Contox uses multiple authentication mechanisms depending on the context. This guide covers each one and when it applies.

API keys

API keys are the primary authentication method for the CLI and MCP server.

Creating an API key

1. Log in to the Contox dashboard at contox.dev
2. Navigate to Settings > API Keys
3. Click Create API Key
4. Copy the key immediately

Storing your API key

CLI storage:

The CLI stores your API key in ~/.contoxrc when you run the login command:

contox login -k <your-api-key>

The ~/.contoxrc file contains your API key and the API URL in JSON format:

{
  "apiKey": "your-api-key",
  "apiUrl": "https://contox.dev"
}

MCP server configuration:

The MCP server reads the API key from the CONTOX_API_KEY environment variable, which is configured in your Claude Desktop config or .mcp.json file.

Environment variable override:

Both the CLI and MCP server check for the CONTOX_API_KEY environment variable first. If set, it takes priority over the ~/.contoxrc file. This is useful in CI/CD pipelines and when the VS Code extension terminal needs to pass credentials.

Bearer token authentication

When making programmatic API calls, the API key is sent as a Bearer token in the Authorization header:

Authorization: Bearer <your-api-key>

This is the authentication method used by the CLI and MCP server when communicating with the Contox API at https://contox.dev/api. You do not need to set this up manually -- the tools handle it automatically.

If you are building a custom integration, include this header in your HTTP requests:

curl -H "Authorization: Bearer <your-api-key>" \
  https://contox.dev/api/projects

HMAC signing

The V2 ingest pipeline uses HMAC (Hash-based Message Authentication Code) signing to verify that session data has not been tampered with in transit.

What is HMAC signing?

HMAC signing creates a cryptographic signature of the request payload using a shared secret. The server verifies the signature before processing the data. This ensures:

• The request came from an authorized client
• The payload was not modified in transit
• The request is authentic

When HMAC signing is used

HMAC signing is required for V2 ingest operations, which include:

• Saving session data (contox save)
• Pushing scan results
• Any write operation through the V2 pipeline

Read operations (loading memory, searching, listing contexts) use standard Bearer token authentication.

HMAC secret management

Each project has its own HMAC secret, which is separate from your API key. The secret is fetched programmatically:

GET /api/projects/{projectId}/hmac-secret

This endpoint requires Bearer token authentication with your API key. The CLI and MCP server handle this automatically -- you do not need to manually fetch or manage HMAC secrets unless you are building a custom integration.

When configuring the MCP server, you can optionally provide the HMAC secret as an environment variable:

{
  "env": {
    "CONTOX_HMAC_SECRET": "your-hmac-secret"
  }
}

If not provided, the MCP server will fetch it automatically using your API key.

Session-based authentication

The Contox dashboard at contox.dev uses session-based authentication through the browser. When you log in via the web interface, a session cookie is set and used for subsequent requests.

This authentication method applies only to the web dashboard. The CLI, MCP server, and VS Code extension all use API key-based authentication.

Security best practices

Protect your API key

• Never commit API keys to version control
• Add ~/.contoxrc to your global gitignore if needed
• If using .mcp.json with inline keys, add it to .gitignore
• Use environment variables in CI/CD instead of hardcoded keys

Key rotation

If you suspect a key has been compromised:

1. Go to Dashboard > Settings > API Keys
2. Delete the compromised key
3. Create a new key
4. Update your ~/.contoxrc with contox login -k <new-key>
5. Update any MCP server configurations with the new key

Environment variable precedence

The authentication resolution order is:

Least privilege

API keys grant access to all projects within your team. If you need to limit access:

• Create separate API keys for different environments (development, staging, production)
• Delete keys that are no longer in use
• Review active keys periodically in the dashboard

Next steps

Now that you understand authentication, follow the First Project guide for a detailed walkthrough of creating and configuring your first Contox project.