Skip to content

Authentication

OpenClaw Hosted uses two complementary authentication paths: Google OAuth for the web dashboard and API keys for programmatic access (CLI, scripts, CI).

Enterprise SSO (SAML/OIDC for your organization) is not shipped — it is on the roadmap. Today, dashboard access requires Google sign-in.

API keys

Format and storage

  • Keys are prefixed with cc_ followed by 64 hex characters (256 bits of entropy).
  • The API stores only a SHA-256 hash of the key. Plaintext keys are returned once at signup or Google login and cannot be recovered afterward.
  • If you lose a key, sign in to the dashboard again (Google login rotates the key) or create a new account via signup.

Using API keys

Send the key on every authenticated Connect RPC request:

1
2
3
POST /openclaw.v1.DeploymentService/ListDeployments
Content-Type: application/json
Authorization: Bearer cc_your_key_here

The CLI and Go client SDK attach this header automatically when configured.

Public endpoints (no key required)

Procedure Purpose
AccountService.Signup Create a new customer
CatalogService.GetLaunchCatalog Read models/channels catalog

All other customer RPCs require a valid key.

Invalid or missing keys

Condition Connect code Typical message
Missing Authorization header unauthenticated missing authorization header
Wrong scheme (not Bearer) unauthenticated authorization header must use Bearer scheme
Unknown or revoked key unauthenticated invalid api key

Dashboard authentication (Google OAuth)

The admin app at www.clusterclaw.ai uses NextAuth with Google as the identity provider.

Flow:

  1. User clicks Continue with Google.
  2. On callback, the server upserts a customers row keyed by Google sub.
  3. A new API key is generated and stored in the HttpOnly cc_api_key cookie.
  4. Dashboard API routes proxy Connect RPC calls to https://api.clusterclaw.ai with that key.

Google sign-in defaults new accounts to the free tier (tier:free entitlement). Paid entitlements from Stripe are preserved across subsequent logins.

API key login (alternative)

You can also paste an existing API key on the login page. The /api/auth/api-key route validates it against GetAccount and sets the same cookie. Useful for automation developers who prefer not to use Google on a given machine.

CLI and SDK configuration

CLI (claw)

Config file: ~/.clusterclaw/config.json

1
2
3
4
{
  "api_url": "https://api.clusterclaw.ai",
  "api_key": "cc_..."
}

Precedence for credentials:

  1. --api-key flag
  2. CLUSTERCLAW_API_KEY environment variable
  3. Config file

Precedence for API URL:

  1. --api-url flag
  2. Config file
  3. Default https://api.clusterclaw.ai

Commands:

1
2
claw login --key cc_your_key_here
claw account          # verifies the key

Go client SDK

1
2
3
4
5
import sdk "github.com/openclaw/openclaw-hosted/packages/client-sdk"

client, err := sdk.ClientFromConfig()
// or
client := sdk.NewClient("https://api.clusterclaw.ai", sdk.WithAPIKey("cc_..."))

The SDK currently wraps DeploymentService and CatalogService. Billing and account calls use the generated Connect clients directly (see CLI auth.go and usage.go for examples).

Runtime tokens (not API keys)

Each deployment receives separate runtime credentials:

Token Prefix Purpose
Gateway token ccgw_* Gateway Control UI / Open Gateway SSO
Inference proxy token ccproxy_* Platform-managed model requests to proxy.clusterclaw.ai

These are not your account API key. They are scoped to a single deployment, injected as environment variables at provision time, and only exposed via GetDeploymentGatewayCredentials under strict guards (owner, public ingress enabled, status HEALTHY).

Never log, cache, or commit runtime tokens.

Authorization model

Authentication identifies which customer owns a request. Authorization rules include:

Rule Behavior
Deployment ownership RPCs scoped to deployment_id verify the deployment belongs to the authenticated customer
Free tier CreateDeployment returns permission_denied — upgrade required
GKE Autopilot target_class: autopilot requires enterprise tier
BYOK provider_api_key required when inference_mode is BYOK; never persisted in the database or echoed in responses

There are no customer-facing roles (admin/member/viewer) within an account today.

CORS and browser access

Browser calls from www.clusterclaw.ai to api.clusterclaw.ai are allowed via CORS. Third-party browser origins are blocked unless explicitly configured by the operator. For custom integrations, call the API from your backend, not a public web page, to keep keys off the client.

Security practices

  • Rotate keys by signing in again (Google) or issuing a new signup (automation accounts).
  • Use CLUSTERCLAW_API_KEY in CI secrets, not repository files.
  • Prefer dashboard SSO for gateway access instead of copying gateway tokens into shared documents.
  • Report suspected key compromise by rotating immediately and reviewing deployment/billing activity.

Planned improvements

  • Organization accounts with multiple users
  • SSO (SAML/OIDC) for dashboard access
  • Scoped API keys (read-only, deployment-scoped)

None of the above are available in the current release.