Authentication methods

The Contox API supports three authentication methods, each designed for different use cases.

Bearer token (API key)

This is the most common authentication method, used by the CLI, MCP server, and any external integration.

Obtaining a key

1. Go to your Dashboard Settings and navigate to the API Keys section
2. Click Create API Key and give it a descriptive name
3. Copy the key immediately -- it is only shown once

Using the key

Include the key in the Authorization header of every request:

curl -X GET https://contox.dev/api/projects \
  -H "Authorization: Bearer contox_sk_abc123def456"

Key format

API keys follow the format contox_sk_<random>. Keys are SHA-256 hashed before storage, so the raw key cannot be retrieved after creation.

Security best practices

• Store keys in environment variables, never in source code
• Rotate keys periodically
• Use separate keys for different environments (development, production)
• Delete keys that are no longer in use

HMAC signature

The V2 ingest endpoint uses HMAC-SHA256 signatures for authentication. This method is designed for high-throughput event ingestion where performance matters.

See HMAC Signing for the complete signing process.

Quick overview

curl -X POST https://contox.dev/api/v2/ingest \
  -H "Content-Type: application/json" \
  -H "X-Contox-Project: proj_abc123" \
  -H "X-Contox-Timestamp: 1705312200" \
  -H "X-Contox-Signature: sha256=abc123..." \
  -d '{"event": "session_save", "payload": {...}}'

Session cookie

When you are signed into the Contox dashboard, a secure HTTP-only session cookie is automatically included with every request. This method is used exclusively by the web dashboard and requires no manual configuration.

Session cookies are:

• HTTP-only -- not accessible via JavaScript
• Secure -- only sent over HTTPS
• SameSite -- restricted to same-site requests

You do not need to manage session cookies manually. They are handled by the browser automatically.

Authentication errors

When authentication fails, the API returns a 401 Unauthorized response:

{
  "error": "Invalid or missing authentication credentials"
}

Common causes:

• Missing Authorization header
• Expired or deleted API key
• Invalid HMAC signature
• Expired session cookie

Next steps

• HMAC Signing -- Detailed guide on HMAC authentication
• API Keys Management -- Create and manage API keys programmatically