API Keys

Overview

API keys provide an alternative to JWT tokens for authenticating API requests. They are ideal for server-to-server integrations, automation scripts, and third-party applications.

Note

Only administrators can create and manage API keys.

Authentication

Include your API key in the X-API-Key header:

curl -X GET "http://your-server:8080/api/contacts" \
  -H "X-API-Key: whm_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

List API Keys

Get all API keys for your organization.

GET /api/api-keys

Response

{
  "status": "success",
  "data": [
    {
      "id": "uuid",
      "name": "Production Integration",
      "key_prefix": "a1b2c3d4e5f6g7h8",
      "last_used_at": "2024-01-15T10:30:00Z",
      "expires_at": "2025-12-31T23:59:59Z",
      "is_active": true,
      "created_at": "2024-01-01T00:00:00Z"
    }
  ]
}

Create API Key

Create a new API key.

POST /api/api-keys

Request Body

{
  "name": "Production Integration",
  "expires_at": "2025-12-31T23:59:59Z"
}

Field	Type	Required	Description
name	string	Yes	Friendly name for the API key
expires_at	string	No	RFC3339 expiration date (null for no expiration)

Response

{
  "status": "success",
  "data": {
    "id": "uuid",
    "name": "Production Integration",
    "key": "whm_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
    "key_prefix": "a1b2c3d4",
    "expires_at": "2025-12-31T23:59:59Z",
    "created_at": "2024-01-01T00:00:00Z"
  }
}

Caution

The full API key is only shown once when created. Store it securely - you won't be able to retrieve it again.

Get API Key

Retrieve a single API key's metadata. The full key is never returned.

GET /api/api-keys/{id}

Response

{
  "status": "success",
  "data": {
    "id": "uuid",
    "name": "Production Integration",
    "key_prefix": "a1b2c3d4e5f6g7h8",
    "last_used_at": "2024-01-15T10:30:00Z",
    "expires_at": "2025-12-31T23:59:59Z",
    "is_active": true,
    "created_at": "2024-01-01T00:00:00Z"
  }
}

Update API Key

Enable or disable an existing API key. Currently only the is_active flag can be changed.

PUT /api/api-keys/{id}

Request Body

{
  "is_active": false
}

Field	Type	Required	Description
is_active	boolean	No	Set false to disable the key without deleting it

Response

{
  "status": "success",
  "data": {
    "id": "uuid",
    "name": "Production Integration",
    "key_prefix": "a1b2c3d4e5f6g7h8",
    "expires_at": "2025-12-31T23:59:59Z",
    "is_active": false,
    "created_at": "2024-01-01T00:00:00Z"
  }
}

Delete API Key

Revoke an API key. This action is immediate and cannot be undone.

DELETE /api/api-keys/{id}

Response

{
  "status": "success",
  "data": {
    "message": "API key deleted successfully"
  }
}

Security Best Practices

1. Store keys securely - Use environment variables or secret management systems
2. Set expiration dates - Use expiring keys when possible for better security
3. Use descriptive names - Name keys by their purpose (e.g., "CI/CD Pipeline", "CRM Integration")
4. Rotate regularly - Delete and recreate keys periodically
5. Limit exposure - Never commit API keys to version control

Key Format

API keys follow the format: whm_ followed by 32 hexadecimal characters.

Example: whm_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

The key_prefix stored and returned by the API is the first 16 characters after the whm_ prefix — enough to identify a key in the UI without exposing the secret.

Permissions

API keys inherit the permissions of the admin user who created them, providing full access to all API endpoints including:

• Contact management and assignment
• Message sending
• Template and flow management
• Campaign management
• Chatbot configuration
• Analytics access