Authentication

HeyCMO uses API key authentication. Every authenticated request must include your API key.

API Key Format

All API keys use the hcmo_live_ prefix followed by a 64-character hex string:

hcmo_live_a1b2c3d4e5f6789...

Authentication Methods

HeyCMO uses two authentication methods depending on the endpoint:

Bearer Token (REST API)

For REST API endpoints (/api/*), include the key as a Bearer token in the Authorization header:

curl -X GET https://heycmo.ai/api/customer/CUSTOMER_ID \
  -H "Authorization: Bearer hcmo_live_YOUR_KEY"

The API extracts the key from the Authorization header by stripping the Bearer prefix.

Token Query Parameter (MCP)

For MCP endpoints (/mcp/sse, /mcp/message), pass the key as a token query parameter:

https://heycmo.ai/mcp/sse?token=hcmo_live_YOUR_KEY

This is the format used in Claude Desktop and Cursor MCP configuration.

Security Architecture

Key Generation

• Keys are generated using 32 bytes of cryptographically secure random data (crypto.randomBytes)
• The full key is shown once at generation time and cannot be retrieved afterward

Key Storage

• Keys are never stored in plaintext on the server
• Only the SHA-256 hash of the key is stored in the database
• Validation uses timing-safe comparison (crypto.timingSafeEqual) to prevent timing attacks

Encryption

• Sensitive data at rest is encrypted with AES-256-GCM
• Encryption uses scrypt-derived keys with a unique IV per ciphertext
• Authentication tags prevent tampering

Customer Validation

After key validation, the system checks that the customer account is in an active or onboarding state. Inactive accounts are rejected even with a valid key.

Rate Limiting

All endpoints have rate limiting applied per API key or IP address:

Best Practices

1. Never expose your API key in client-side code, public repositories, or logs
2. Use environment variables to store your key in server applications
3. Rotate keys periodically — generate a new key and revoke the old one
4. Use separate keys for development and production environments
5. Monitor usage via the dashboard to detect unauthorized access

Error Responses

Missing API Key

// HTTP 401
{
  "error": "Authorization header required"
}

Invalid API Key

// HTTP 401
{
  "error": "Invalid API key"
}

MCP Token Missing

// HTTP 401
{
  "error": "MCP token required. Include ?token=hcmo_live_..."
}

Inactive Account

// HTTP 401
{
  "error": "Customer account is not active"
}

Rate Limited

// HTTP 429
{
  "error": "Rate limit exceeded. Try again later."
}