Skip to main content

API Key Management

Create, manage, and secure your HueChat API keys.

Creating Keys​

Via Dashboard​

  1. Go to app.huechat.ai/settings/api-keys
  2. Click Create API Key
  3. Enter a name (e.g., "Production Server", "Zapier Integration")
  4. Select permissions
  5. Click Create
  6. Copy the key immediately (shown only once!)

Key Naming Conventions​

Use descriptive names to track key usage:

Good NamesBad Names
Production BackendKey 1
Staging EnvironmentTest
CRM Integrationabc123
Marketing AutomationMy Key

Permissions​

Full Access​

Grants access to all API endpoints. Use for trusted internal systems.

Custom Permissions​

Limit access to specific operations:

contacts:read     - View contacts
contacts:write    - Create/update/delete contacts
conversations:read    - View conversations and messages
conversations:write   - Send messages, update 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

Example: Read-Only Analytics Key​

Perfect for dashboards that only need to view data:

Permissions:
✓ contacts:read
✓ conversations:read
✓ admin:read
✗ (all write permissions)

Example: Messaging-Only Key​

For systems that only need to send messages:

Permissions:
✓ contacts:read
✓ contacts:write
✓ conversations:write
✗ admin:*
✗ webhooks:*

Key Storage​

# .env (never commit!)
HUECHAT_API_KEY=sk_live_abc123xyz789

# .env.example (safe to commit)
HUECHAT_API_KEY=sk_live_your_key_here

Secret Managers​

For production environments, use dedicated secret managers:

PlatformService
AWSSecrets Manager
GCPSecret Manager
AzureKey Vault
VercelEnvironment Variables
RailwayVariables
HerokuConfig Vars

Example: Node.js with dotenv​

require('dotenv').config();

const apiKey = process.env.HUECHAT_API_KEY;

if (!apiKey) {
  throw new Error('HUECHAT_API_KEY is required');
}

Example: Python with python-dotenv​

import os
from dotenv import load_dotenv

load_dotenv()

api_key = os.getenv('HUECHAT_API_KEY')

if not api_key:
    raise ValueError('HUECHAT_API_KEY is required')

Key Rotation​

Rotate your API keys regularly to maintain security.

Rotation Steps​

  1. Create a new key with the same permissions
  2. Update your application configuration
  3. Deploy the update
  4. Verify the new key works
  5. Delete the old key

Zero-Downtime Rotation​

# Support both old and new keys during transition
import os

api_keys = [
    os.getenv('HUECHAT_API_KEY'),
    os.getenv('HUECHAT_API_KEY_OLD'),  # Temporary during rotation
]

# Remove None values
api_keys = [k for k in api_keys if k]

Revoking Keys​

warning

Revoking a key immediately stops all API access using that key.

When to Revoke​

  • Key was accidentally exposed
  • Employee with key access left
  • Suspicious activity detected
  • Key is no longer needed

How to Revoke​

  1. Go to Settings > API Keys
  2. Find the key to revoke
  3. Click the delete icon
  4. Confirm deletion

Audit Logs​

Track API key usage in the dashboard:

  • Last used timestamp
  • Requests per day
  • Error rates
  • Endpoint usage

Enterprise plans include detailed audit logs with:

  • Full request/response logging
  • IP addresses
  • Geographic location
  • User agent strings

Best Practices Checklist​

  • Store keys in environment variables
  • Never commit keys to version control
  • Use separate keys for each environment
  • Use test keys during development
  • Apply minimum necessary permissions
  • Rotate keys every 90 days
  • Monitor key usage for anomalies
  • Revoke unused keys promptly