Authentication

Gateway API authentication mechanisms

Authentication

The OpenClaw Gateway API supports multiple authentication methods to secure access to your agents and data.

Authentication Methods

Bearer Token

The primary authentication method. Include your token in the Authorization header:

Authorization: Bearer your-token-here

Configuration:

gateway:
  auth:
    token: "your-secret-token"

Example request:

curl -X POST http://localhost:18789/v1/chat/completions \
  -H "Authorization: Bearer your-token-here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openclaw",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Password Authentication

Alternative to token-based auth:

gateway:
  auth:
    password: "your-password"

Send password as Bearer token:

Authorization: Bearer your-password

Device Token Authentication

For mobile and desktop clients, device tokens are issued after pairing:

1. Client requests pairing via node.pair.request
2. Gateway admin approves via node.pair.approve
3. Client receives a device token
4. Client authenticates with device token

WebSocket connection with device token:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "connect",
  "params": {
    "role": "node",
    "auth": {
      "token": "device-token-here"
    }
  }
}

See Device Pairing for details.

Tailscale Authentication

When running behind Tailscale Serve, the Gateway can authenticate users via Tailscale identity:

gateway:
  tailscale:
    mode: enabled  # or "require"

Modes:

• enabled - Allow Tailscale auth alongside token/password
• require - Only accept Tailscale-authenticated requests
• disabled - Disable Tailscale auth

Tailscale authentication reads Tailscale-User-Login headers injected by Tailscale Serve.

Trusted Proxy Authentication

For trusted reverse proxies (e.g., Cloudflare, nginx):

gateway:
  auth:
    trustedProxy:
      enabled: true
      header: "X-Forwarded-User"
  trustedProxies:
    - "10.0.0.1"
    - "192.168.1.0/24"

The Gateway validates the client IP against trustedProxies and reads the user identity from the configured header.

Local Loopback (No Auth)

Requests from localhost (127.0.0.1, ::1) are automatically authenticated when:

• Client IP is loopback
• Host header is localhost, 127.0.0.1, or ::1
• No proxy forwarding headers present

This allows local CLI tools to access the Gateway without explicit credentials.

Authentication Priority

The Gateway checks authentication methods in this order:

1. Local loopback - Bypass auth for local requests
2. Device token - Check device token from pairing
3. Bearer token - Check configured token
4. Password - Check configured password
5. Tailscale - Check Tailscale identity (if enabled)
6. Trusted proxy - Check proxy header (if enabled)

First successful method authenticates the request.

Rate Limiting

To prevent brute-force attacks, the Gateway rate-limits failed authentication attempts:

• Limit: 20 failures per client per 60-second window
• Tracking: By client IP address
• Response: HTTP 429 Too Many Requests with Retry-After header

Rate limit response:

{
  "error": {
    "message": "Too many failed authentication attempts. Please try again later.",
    "type": "rate_limited"
  }
}

Response headers:

HTTP/1.1 429 Too Many Requests
Retry-After: 42
Content-Type: application/json

WebSocket Authentication

WebSocket connections authenticate during the initial connect handshake:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "connect",
  "params": {
    "role": "control",
    "auth": {
      "token": "your-token-here"
    },
    "client": {
      "name": "My Client",
      "version": "1.0.0"
    }
  }
}

Roles:

• control - Full control plane access
• node - Device/node role (mobile, desktop)
• webchat - Web chat interface

See WebSocket Protocol for details.

HTTP Authentication

HTTP endpoints authenticate via Authorization header:

Authorization: Bearer your-token-here

Or via custom header (for hooks):

X-OpenClaw-Token: your-token-here

Security Best Practices

Use strong tokens

Generate tokens with sufficient entropy:

openssl rand -hex 32

Store tokens securely (environment variables, secret managers).

Limit network exposure

Bind Gateway to loopback when possible:

gateway:
  bind: loopback  # only accessible from localhost

Use Tailscale or VPN for remote access instead of exposing to the internet.

Rotate tokens regularly

For device tokens, use rotation endpoints:

{"method": "device.token.rotate", "params": {"deviceId": "..."}}

Monitor authentication failures

Gateway logs failed authentication attempts. Monitor for suspicious activity:

openclaw logs | grep "auth failed"

Troubleshooting

401 Unauthorized:

• Verify token matches gateway.auth.token in config
• Check token is sent in Authorization: Bearer header
• Ensure no extra whitespace in token

429 Rate Limited:

• Wait for the Retry-After duration
• Check for authentication failures in logs
• Verify token is correct to avoid repeated failures

Connection refused:

• Verify Gateway is running: openclaw status
• Check bind address: openclaw config get gateway.bind
• Confirm port: openclaw config get gateway.port

Next Steps

WebSocket Protocol

Connect via WebSocket

Device Pairing

Pair mobile/desktop devices