Authentication Overview

HueChat uses API key authentication - simple, secure, and designed for business integrations.

How It Works

Every API request requires an API key passed in the request header:

curl https://api.huechat.ai/v2/contacts \
  -H "X-API-Key: sk_live_your_api_key_here"

That's it! No OAuth flows, no token refresh, no JWT expiration to handle.

Why API Keys?

We chose API keys for HueChat API because:

Benefit	Description
Simple	One header, works everywhere
Secure	Server-to-server, never exposed to browsers
Reliable	No token expiration or refresh logic
Auditable	Each key can be tracked and revoked

Authentication Methods

Primary: X-API-Key Header

curl https://api.huechat.ai/v2/contacts \
  -H "X-API-Key: sk_live_your_api_key"

Alternative: Authorization Header

curl https://api.huechat.ai/v2/contacts \
  -H "Authorization: Bearer sk_live_your_api_key"

Both methods are equivalent. Use whichever fits your HTTP client or framework.

Key Types

Type	Prefix	Environment	Real Messages?
Live	sk_live_	Production	Yes
Test	sk_test_	Sandbox	No (simulated)

Live Keys

• Use with https://api.huechat.ai/v2
• Send real messages to real contacts
• Messages count toward your plan limits

Test Keys

• Use with https://sandbox.huechat.ai/v2
• Messages are simulated (not actually sent)
• Responses mirror production behavior
• Perfect for development and testing

Security Model

┌─────────────────────────────────────────┐
│           Your Backend Server            │
│                                          │
│  ┌──────────────────────────────────┐   │
│  │     HUECHAT_API_KEY (env var)    │   │
│  └──────────────────────────────────┘   │
│                  │                       │
│                  ▼                       │
│  ┌──────────────────────────────────┐   │
│  │        API Request Handler        │   │
│  │   X-API-Key: sk_live_xxx         │   │
│  └──────────────────────────────────┘   │
│                  │                       │
└──────────────────│───────────────────────┘
                   │ HTTPS
                   ▼
┌─────────────────────────────────────────┐
│          HueChat API Server              │
│   api.huechat.ai                        │
└─────────────────────────────────────────┘

Key Points

1. Server-side only: API keys should never be in client-side code
2. HTTPS required: All API traffic is encrypted
3. IP restrictions (Enterprise): Lock keys to specific IPs

Error Responses

Missing API Key

{
  "error": "unauthorized",
  "message": "API key is required",
  "code": 401
}

Invalid API Key

{
  "error": "unauthorized",
  "message": "Invalid API key",
  "code": 401
}

Insufficient Permissions

{
  "error": "forbidden",
  "message": "API key does not have permission for this action",
  "code": 403
}

Next Steps

• API Key Management - Creating and managing keys
• Rate Limits - Request limits and handling