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 "https://dashboard.cloudwa.net/api/contacts" \
  -H "X-API-Key: whm_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

List API Keys

Get all API keys for your organization.

GET /api/api-keys

Query Parameters

Parameter	Type	Description
search	string	Filter by name or key prefix (case-insensitive)
page	integer	Page number for pagination (default: 1)
limit	integer	Items per page (default: 50)

Response

{
  "status": "success",
  "data": {
    "api_keys": [
      {
        "id": "uuid",
        "name": "Production Integration",
        "key_prefix": "a1b2c3d4",
        "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"
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 50
  }
}

Get API Key

Get details of a specific API key by its ID.

GET /api/api-keys/{id}

Path Parameters

Parameter	Type	Description
id	string	The unique UUID of the API key

Response

{
  "status": "success",
  "data": {
    "id": "uuid",
    "name": "Production Integration",
    "key_prefix": "a1b2c3d4",
    "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.

Update API Key

Update details of a specific API key (currently supports updating active status).

PUT /api/api-keys/{id}

Path Parameters

Parameter	Type	Description
id	string	The unique UUID of the API key

Request Body

{
  "is_active": false
}

Field	Type	Required	Description
is_active	boolean	Yes	Enable or disable the API key

Response

{
  "status": "success",
  "data": {
    "id": "uuid",
    "name": "Production Integration",
    "key_prefix": "a1b2c3d4",
    "last_used_at": "2024-01-15T10:30:00Z",
    "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

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