API Authentication

All ClawHQ API endpoints require authentication via API keys. This page covers how to create, manage, and use API keys to authenticate your requests.

Plan Requirements PRO

API access is available on the Pro plan and above. Starter plan users can upgrade from the Billing page in the dashboard. The API is included at no additional cost with your Pro or Ultra subscription.

API Key Format

ClawHQ API keys follow a consistent format for easy identification:

• Prefix: All keys begin with clw_
• Length: 36 characters total (including the prefix)
• Character set: Alphanumeric characters (a-z, 0-9)

Example key:

clw_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Creating API Keys

API keys are created and managed from the API Access page in your ClawHQ dashboard.

1. Navigate to the API Access section in the dashboard sidebar
2. Click Create New Key
3. Enter a descriptive name for the key (e.g., "Production Backend", "Staging Environment")
4. Select a rate limit tier (30, 60, 120, or 300 requests per minute)
5. Click Generate
6. Copy the key immediately — it will not be shown again

You can create multiple API keys for different environments or services. Each key has its own rate limit and can be independently revoked.

Using API Keys

Include your API key in the Authorization header of every request using the Bearer token scheme:

Authorization: Bearer $CLAWHQ_API_KEY

Key Validation

When the API receives a request, it performs the following validation steps:

1. Format check — Verifies the key starts with clw_ and is 36 characters
2. Hash lookup — The key is hashed using SHA-256 and compared against stored hashes in the database. Raw keys are never stored.
3. Plan check — Confirms the associated account has an active Pro or Ultra subscription
4. Rate limit check — Verifies the key has not exceeded its configured requests-per-minute limit

If any step fails, the API returns an appropriate error response (see Error Responses below).

Code Examples

cURL

curl -X POST https://app.clawhq.tech/api/v1/chat \
  -H "Authorization: Bearer $CLAWHQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello, how can I help you?"}'

Python

import os
import requests

API_KEY = os.environ["CLAWHQ_API_KEY"]
BASE_URL = "https://app.clawhq.tech/api/v1"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

response = requests.post(
    f"{BASE_URL}/chat",
    headers=headers,
    json={"message": "Hello, how can I help you?"}
)

print(response.json())

JavaScript

const API_KEY = process.env.CLAWHQ_API_KEY;
const BASE_URL = "https://app.clawhq.tech/api/v1";

const response = await fetch(`${BASE_URL}/chat`, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    message: "Hello, how can I help you?",
  }),
});

const data = await response.json();
console.log(data);

Error Responses

Authentication errors return standard HTTP status codes with a JSON error body:

Example error response:

{
  "error": "Invalid API key",
  "code": "INVALID_KEY",
  "status": 401
}

Security Best Practices

• Never expose API keys in client-side code, public repositories, or browser requests
• Use environment variables to store keys in your application
• Create separate keys for each environment (development, staging, production)
• Rotate keys periodically by creating a new key and revoking the old one
• Set the lowest rate limit that meets your needs to minimize blast radius if a key is compromised
• Monitor key usage on the API Access page to detect anomalous patterns

Next Steps

• Chat API — Send messages and receive AI responses
• Agents API — List your deployed agents
• Rate Limits — Understand rate limiting and best practices