API Authentication & Rate Limiting

+15 Mana ✨
OpenClaw HTTP API(DOCUMENTATION)

Introduction

Securing the OpenClaw HTTP API is critical for production deployments. OpenClaw supports token-based authentication and configurable rate limiting to protect your gateway from unauthorized access and abuse.

Key Concepts

  • Bearer Token Auth: API requests are authenticated with a Bearer token in the Authorization header.
  • API Key Management: Keys are created and managed via openclaw api keys commands.
  • Rate Limiting: Configurable per-key limits on requests per minute, concurrent connections, and token usage.
  • Key Scoping: API keys can be scoped to specific agents, tools, or operations.

Real World Context

A startup exposes their OpenClaw API to internal microservices. Each service gets its own API key with rate limits tuned to its expected usage: the CI pipeline gets 100 requests/minute, the monitoring service gets 10, and developer IDE access gets 30. If any service goes haywire, rate limiting prevents it from overwhelming the gateway.

Deep Dive

Create and manage API keys via the CLI:

bash
# Create a new API key
openclaw api keys create \
  --name "ci-pipeline" \
  --agents "deployer" \
  --rate-limit 100

# List existing keys
openclaw api keys list

# Revoke a key
openclaw api keys revoke ci-pipeline

The --agents flag scopes the key to specific agents. The --rate-limit flag sets the maximum requests per minute for this key. The create command outputs the key value, which should be stored securely.

Configure rate limiting in the gateway configuration:

json
{
  "api": {
    "enabled": true,
    "rateLimiting": {
      "global": {
        "requestsPerMinute": 500,
        "concurrentConnections": 50
      },
      "perKey": {
        "defaultRequestsPerMinute": 60,
        "defaultConcurrentConnections": 5
      }
    }
  }
}

This sets a global limit of 500 requests/minute and 50 concurrent connections across all keys. Individual keys default to 60 requests/minute and 5 concurrent connections, unless overridden when creating the key.

Rate-limited requests receive a 429 response with retry headers:

bash
# Response when rate limited:
# HTTP/1.1 429 Too Many Requests
# Retry-After: 12
# X-RateLimit-Remaining: 0
# X-RateLimit-Reset: 1708425600

The Retry-After header tells the client how many seconds to wait before retrying.

Common Pitfalls

  1. Running without API authentication in production — An unauthenticated API lets anyone on the network use your gateway. Always require API keys.
  2. Setting rate limits too high — Liberal rate limits can allow a single misbehaving client to saturate your GPU or exhaust your model provider quota.

Best Practices

  1. Rotate API keys regularly — Use openclaw api keys create to generate new keys and revoke to retire old ones on a quarterly schedule.
  2. Monitor rate limit hits — Frequent 429 responses indicate a client needs a higher limit or is misbehaving.

Summary

  • Bearer token authentication secures the OpenClaw HTTP API
  • API keys are created, listed, and revoked via the CLI
  • Keys can be scoped to specific agents and rate-limited
  • Global and per-key rate limits prevent abuse and resource exhaustion
  • Rate-limited requests get 429 responses with Retry-After headers
✓ Completed