Gateway Authentication Mechanisms Explained

Why Authentication Matters

If OpenClaw Gateway API endpoints are left unprotected, anyone can send requests that consume your model quota or access sensitive data. Authentication ensures only authorized clients can access the Gateway service.

Authentication Methods Overview

OpenClaw supports multiple authentication methods:

API Key Authentication: Simple and direct, suitable for internal use
JWT Token Authentication: Ideal for web application integration
OAuth 2.0: Suitable for enterprise-grade integration
Webhook Signature Verification: For channel webhook security

API Key Authentication

The most basic authentication method, passing an API key via request headers:

{
  "security": {
    "auth": {
      "type": "api-key",
      "keys": [
        {
          "name": "admin",
          "key": "{{GATEWAY_ADMIN_KEY}}",
          "permissions": ["*"]
        },
        {
          "name": "readonly",
          "key": "{{GATEWAY_READ_KEY}}",
          "permissions": ["read", "chat"]
        }
      ]
    }
  }
}

Generate API keys:

openclaw secrets set GATEWAY_ADMIN_KEY "$(openssl rand -hex 32)"
openclaw secrets set GATEWAY_READ_KEY "$(openssl rand -hex 32)"

Client usage:

curl -H "Authorization: Bearer your-api-key" \
  https://gateway.example.com/api/chat

Permission Control

Assign different permissions to different API keys:

{
  "security": {
    "auth": {
      "keys": [
        {
          "name": "full-access",
          "key": "{{KEY_FULL}}",
          "permissions": ["*"]
        },
        {
          "name": "chat-only",
          "key": "{{KEY_CHAT}}",
          "permissions": ["chat"]
        },
        {
          "name": "admin",
          "key": "{{KEY_ADMIN}}",
          "permissions": ["admin", "config", "secrets"]
        }
      ]
    }
  }
}

Available permissions:

chat: Send and receive messages
read: Read configuration and status
admin: Manage configuration and users
config: Modify configuration
secrets: Manage secrets
*: All permissions

JWT Authentication

{
  "security": {
    "auth": {
      "type": "jwt",
      "jwt": {
        "secret": "{{JWT_SECRET}}",
        "algorithm": "HS256",
        "issuer": "openclaw",
        "expiresIn": "24h",
        "claims": {
          "requiredClaims": ["sub", "role"]
        }
      }
    }
  }
}

Generate a JWT token:

openclaw auth token --user admin --role admin --expires 24h

Webhook Signature Verification

Ensure webhook requests come from legitimate sources:

{
  "channels": {
    "telegram": {
      "webhookSecret": "{{TELEGRAM_WEBHOOK_SECRET}}",
      "verifySignature": true
    }
  }
}

IP Whitelist

Restrict which IP addresses can access the Gateway:

{
  "security": {
    "ipWhitelist": {
      "enabled": true,
      "addresses": [
        "10.0.0.0/8",
        "192.168.1.0/24",
        "203.0.113.50"
      ]
    }
  }
}

CORS Configuration

Control which domains can access the Gateway API:

{
  "gateway": {
    "cors": {
      "origins": ["https://your-app.com"],
      "methods": ["GET", "POST"],
      "headers": ["Authorization", "Content-Type"],
      "credentials": true
    }
  }
}

Rate Limiting with Authentication

Set different rate limits for different authentication levels:

{
  "security": {
    "rateLimit": {
      "authenticated": {
        "maxRequests": 100,
        "window": 60
      },
      "unauthenticated": {
        "maxRequests": 10,
        "window": 60
      }
    }
  }
}

Audit Log

Log all authentication-related events:

{
  "security": {
    "audit": {
      "enabled": true,
      "events": ["auth.success", "auth.failure", "auth.token.created"],
      "logFile": "~/.openclaw/logs/auth-audit.log"
    }
  }
}

Troubleshooting

401 Unauthorized:

Check that the API key is correct
Verify the Authorization header format is Bearer <key>

403 Forbidden:

The API key is valid but lacks the required permissions
Check the key's permissions configuration

IP Denied:

Check the IP whitelist configuration
Confirm the client's actual IP (be aware of proxies and load balancers)

Summary

Gateway authentication is the first line of defense for protecting your OpenClaw service. Choose the right authentication method for your use case: API keys for internal use, JWT for web integration, OAuth for enterprise integration. Regardless of which method you choose, always use it alongside IP whitelisting and rate limiting.