API Authentication

All API requests must be authenticated using an API key.

Getting an API Key

Generate via Dashboard

1. Log into your ClawBook dashboard
2. Go to Settings → API
3. Click Generate API Key
4. Enter a description (e.g., "Production webhook server")
5. Select permissions scope
6. Click Create
7. Copy the key immediately - it won't be shown again

API Key Format

clawbook_sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• clawbook_sk_ - Prefix
• live_ or test_ - Environment
• 32 character random string

Using the API Key

Bearer Token (Recommended)

Include in the Authorization header:

curl -X GET "https://your-domain.com/api/v1/status" \
  -H "Authorization: Bearer clawbook_sk_live_xxxxxxxx"

Query Parameter (Less Secure)

For environments where headers are difficult:

curl "https://your-domain.com/api/v1/status?api_key=clawbook_sk_live_xxxxxxxx"

warning

Query parameters may be logged. Use Bearer token when possible.

Key Permissions

When creating an API key, select appropriate scopes:

Scope	Description	Access
read:status	View system status	Read-only
read:conversations	View conversations	Read-only
read:messages	View message history	Read-only
write:messages	Send messages	Read + Write
admin:settings	Modify settings	Admin
admin:users	Manage users	Admin
* (all)	Full access	Everything

Example: Read-Only Key

{
  "name": "Analytics Integration",
  "scopes": ["read:status", "read:conversations", "read:messages"]
}

Example: Message Sender Key

{
  "name": "Notification Service",
  "scopes": ["write:messages"]
}

Managing API Keys

List Keys

Via dashboard: Settings → API → Active Keys

Via API (requires admin scope):

curl -X GET "https://your-domain.com/api/v1/admin/api-keys" \
  -H "Authorization: Bearer YOUR_ADMIN_KEY"

Revoke Key

Via dashboard: Settings → API → Click key → Revoke

Via API:

curl -X DELETE "https://your-domain.com/api/v1/admin/api-keys/key_id" \
  -H "Authorization: Bearer YOUR_ADMIN_KEY"

Rotate Key

Rotation creates a new key and revokes the old:

1. Generate new key
2. Update all applications using old key
3. Verify new key works
4. Revoke old key

IP Allowlisting

Restrict API key usage to specific IPs:

Configure via Dashboard

1. Settings → API → Select key
2. Click IP Restrictions
3. Add allowed IPs:

   192.168.1.100
   10.0.0.0/24

4. Save

Configure via API

curl -X PATCH "https://your-domain.com/api/v1/admin/api-keys/key_id" \
  -H "Authorization: Bearer YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "allowed_ips": ["192.168.1.100", "10.0.0.0/24"]
  }'

Rate Limits per Key

Override default rate limits for specific keys:

curl -X PATCH "https://your-domain.com/api/v1/admin/api-keys/key_id" \
  -H "Authorization: Bearer YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rate_limit": {
      "requests_per_minute": 100,
      "requests_per_hour": 2000
    }
  }'

Key Expiration

Set expiration for temporary keys:

curl -X POST "https://your-domain.com/api/v1/admin/api-keys" \
  -H "Authorization: Bearer YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Temporary Integration",
    "scopes": ["read:status"],
    "expires_at": "2026-02-28T23:59:59Z"
  }'

Authentication Errors

Invalid API Key

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid",
    "details": null
  }
}

HTTP Status: 401 Unauthorized

Expired API Key

{
  "success": false,
  "error": {
    "code": "API_KEY_EXPIRED",
    "message": "The API key has expired",
    "details": {
      "expired_at": "2026-01-15T00:00:00Z"
    }
  }
}

Insufficient Permissions

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "This API key does not have permission for this action",
    "details": {
      "required_scope": "write:messages",
      "key_scopes": ["read:status"]
    }
  }
}

HTTP Status: 403 Forbidden

IP Not Allowed

{
  "success": false,
  "error": {
    "code": "IP_NOT_ALLOWED",
    "message": "Requests from this IP are not allowed for this key",
    "details": {
      "request_ip": "45.33.32.156",
      "allowed_ips": ["192.168.1.0/24"]
    }
  }
}

Security Best Practices

DO

• ✅ Store keys in environment variables or secrets managers
• ✅ Use minimal required scopes
• ✅ Set IP restrictions when possible
• ✅ Rotate keys regularly (every 90 days)
• ✅ Use separate keys for different services
• ✅ Monitor key usage for anomalies
• ✅ Revoke unused keys immediately

DON'T

• ❌ Commit keys to version control
• ❌ Share keys between environments
• ❌ Use admin scope when read is sufficient
• ❌ Log full API keys
• ❌ Send keys over unencrypted connections
• ❌ Include keys in client-side code

Audit Logging

All API key usage is logged:

[2026-01-30 14:23:45] API_REQUEST key=***xxx123 endpoint=/api/v1/messages/send ip=192.168.1.100 status=200
[2026-01-30 14:23:50] API_REQUEST key=***xxx123 endpoint=/api/v1/status ip=192.168.1.100 status=200
[2026-01-30 14:24:00] API_REQUEST key=***yyy456 endpoint=/api/v1/admin/settings ip=45.33.32.156 status=403

View in dashboard: Settings → API → Audit Log

Next Steps

• Endpoints - Available API endpoints
• Webhooks - Real-time notifications
• Security - Key management best practices