API Keys

Learn how to create and manage API keys for authenticating with the HueChat API.

Overview

API keys are the only authentication method for HueChat API. They're simple, secure, and designed for business integrations.

Creating an API Key

1. Log into HueChat Dashboard
2. Navigate to Settings > API Keys
3. Click Create API Key
4. Give your key a descriptive name (e.g., "Production Server", "CRM Integration")
5. Select permissions (Full Access or Custom)
6. Click Create
7. Copy your key immediately - it won't be shown again!

Key Types

Type	Prefix	Use For
Live	sk_live_	Production environment
Test	sk_test_	Development & sandbox testing

Live Keys

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

Test Keys

• Messages are simulated (not actually sent)
• Use with https://sandbox.huechat.ai/v2
• Free and unlimited for development

Using Your API Key

Include your API key in the X-API-Key header with every request:

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

Alternative Header Format

You can also use the Authorization header with a Bearer prefix:

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

Key Permissions

When creating a key, you can choose:

Full Access

• All endpoints available
• Read and write permissions
• Best for trusted server-side integrations

Custom Permissions

Select specific scopes:

Scope	Description
contacts:read	Read contact information
contacts:write	Create/update/delete contacts
conversations:read	Read conversations and messages
conversations:write	Send messages, resolve conversations
channels:read	View connected channels
channels:write	Connect/disconnect channels
webhooks:manage	Create/update/delete webhooks
admin:read	View users and analytics
admin:write	Manage users and settings

Security Best Practices

Do

• Store API keys in environment variables
• Use test keys during development
• Rotate keys every 90 days
• Use separate keys for each integration
• Restrict permissions to only what's needed

Don't

• Commit API keys to version control
• Expose keys in client-side JavaScript
• Share keys via email or chat
• Use live keys in development/staging

Environment Variables

Store your API key securely:

# .env file (never commit this!)
HUECHAT_API_KEY=sk_live_your_key_here

// Node.js
const apiKey = process.env.HUECHAT_API_KEY;

# Python
import os
api_key = os.environ.get('HUECHAT_API_KEY')

// Go
apiKey := os.Getenv("HUECHAT_API_KEY")

Managing Keys

View All Keys

In the dashboard, go to Settings > API Keys to see:

• Key name
• Partial key (last 4 characters)
• Created date
• Last used date
• Permissions

Rotate a Key

1. Create a new key with the same permissions
2. Update your application to use the new key
3. Delete the old key

Delete a Key

caution

Deleting a key immediately revokes access. Ensure no active integrations are using it.

1. Go to Settings > API Keys
2. Click the trash icon next to the key
3. Confirm deletion

Rate Limits

API keys have rate limits based on your plan:

Plan	Requests/Minute
Free	100
Pro	1,000
Enterprise	Custom

Rate limit headers are included in every response:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1706215200

See Rate Limits for more details.