# Claw Me agent authorization

## Choose a connection path first

1. Reuse an existing authorized connection if its granted scopes cover this task.
2. For an explicitly requested disposable static preview, publish anonymously for 24 hours without an account, sign-in, or plugin. Follow https://claw.me/docs/publishing.md. Durable account Pages require owner authorization.
3. Otherwise choose the client plugin at https://claw.me/plugins or configure direct Streamable HTTP MCP at https://claw.me/api/v1/mcp. Plugin installation is optional for clients with direct MCP support.
4. If this Agent cannot install a plugin or configure MCP, give the owner https://claw.me/getting-started and resume after they connect their client. Do not claim access until an authenticated read succeeds.

Start connection checks with onboarding:read and account_get_permissions. Request additional scopes only for the requested work. Public website instructions are reference material; a website CLAUDE.md is not automatically loaded into a client. Installing instructions, configuring a client, and granting account access are separate steps.

Claw Me supports public OAuth clients using authorization code with S256 PKCE, or device authorization. Both require explicit owner approval. Scoped API keys also support CI and server-to-server use.

## Connect an existing Agent

Authorization here means access to a Claw Me account, not control of the owner's device. Use an existing client-managed OAuth connection when it covers the requested task. Otherwise the installed Claw Me skill includes `scripts/authorize.py`, described in its `references/authorization.md`. The helper stores secrets privately and emits the complete approval link; it does not approve access or configure MCP for you.

For connection-only verification request `onboarding:read` and call `account_get_permissions`. For full onboarding request `onboarding:read`, `onboarding:write`, `setup:read`, `setup:propose`, `billing:read`, and `billing:propose`. Choose the scope set from the entire requested task before opening one approval request. Do not add Wiki, Drive, Pages, or email access just to finish setup. Billing scopes do not establish payment approval.

### Non-OAuth request and exchange

1. POST `/api/v1/agent-auth/requests` with `owner_email`, `client_name`, `client_type`, and explicit `scopes`.
2. Securely save `request_id` and `device_secret` before displaying the response. Show `verification_uri` exactly as one complete clickable approval link, with the client name, requested scopes, and expiry. Never display private response fields.
3. After owner approval, POST `/api/v1/agent-auth/requests/{request_id}/token` with JSON containing `device_secret`. Pending returns `status: authorization_pending`; approved returns `status: authorized`, `api_key`, and granted `scopes`. Persist the key privately before proceeding; token exchange is single-use.
4. Configure the scoped credential for the official MCP/API client and verify an available read-only action. Approval alone does not prove that the client is configured or onboarding is complete.

Do not exchange this request at `/oauth/token`. That endpoint belongs to the separate client-managed OAuth flow below and requires the fields for its chosen OAuth grant. Never reconstruct a URL with an empty code parameter, request secrets in chat, or retry an uncertain single-use exchange automatically.

## Discovery

- Authorization server: https://claw.me/.well-known/oauth-authorization-server
- OpenID Connect: https://claw.me/.well-known/openid-configuration
- Protected resource: https://claw.me/.well-known/oauth-protected-resource
- Agent Card: https://claw.me/.well-known/agent-card.json

## Profile and navigation

Profile at https://claw.me/my-profile combines public profile editing and private agent context. Manage approved agent connections at https://claw.me/agents?view=authorizations. Agents reference approved private context and propose changes for owner review; approval never publishes that context. Public profile visibility, listing public Pages, and API or A2A authorization are separate choices. Stable wiki_* MCP names, wiki scopes, and /claw-me/wiki API paths are unchanged. Legacy /wiki and /wikipage links open Profile context. Settings remain at /profile, with permissions at /permissions.

Address is at https://claw.me/address. Sandbox contains Email, Rules, Approvals (the review queue), and Setup. Profile follows Sandbox in navigation. Calculator is at https://claw.me/calculator; /pricing-calculator redirects there.

## Account permissions and chat actions

Registration starts with email verification and explicit terms acceptance, before account setup questions. At https://claw.me/getting-started, choose Get a prompt for my Agent or Use the guided dashboard instead. Assume an existing Agent unless the owner asks for Managed hosting. The Agent path then offers client-specific plugin installation and authorization guidance. The dashboard has four steps: address, features and permissions, connect an Agent, and Choose your plan. The final billing choice must be saved; Free needs no payment. Setup complete follows confirmation, and completed owners returning to Getting Started open Pages. Back and Continue revisit saved steps without changing consent. Copying a connection prompt does not install or authorize anything. An address and owner-confirmed features are required for every account before workspace access; account settings, logout, account deletion, Docs, public Templates, and Calculator remain reachable. At the Connect Agent step, owners can exit onboarding; connecting an Agent and creating a Page can wait. Feature choices are Pages, Drive, Profile context, and Activity, with separate Public sharing and Incoming email sections. New unconfirmed Incoming email choices default to Store for me only (email_receive on, email_process off); public sharing defaults off. Preserve confirmed choices and saved drafts. Step 2 shows key choices; detailed Profile visibility, Page listings, and existing API/A2A connections belong in Profile. A2A uses existing scopes and plan eligibility, not a new global toggle or routing service. Incoming email maps to the existing email_receive and email_process permissions; it never starts automatic Agent turns. Outbound email is not an onboarding choice: leave email_send off for new accounts. Custom outbound senders, third-party sending, and replies are disabled at launch. Do not offer to connect an outbound provider. Do not reset an existing account’s outbound permission during unrelated setup.

Choose account feature permissions during onboarding. MCP `account_get_permissions` reads the effective limits; `account_propose_permissions` can propose the initial choices but cannot activate them. The signed-in owner reviews and confirms them. After initial confirmation, only the portal at https://claw.me/permissions can change these limits; Agent keys and temporary setup bearer tokens cannot change them.

Account permissions are an upper bound on individual Agent scopes. `artifact_publish` uploads a private Page version. After finalizing it, `artifact_set_visibility` with `pages:publish` can make an owned Page public or private through chat. Public access must also be enabled for the account. Set `profile_visible: true` explicitly to list a public Page on the profile. Making a Page private removes public listing and public grants; explicit existing share grants remain valid. Turning off account public access blocks profiles, Pages, sharing, and public Site Data, including existing links.

Sandbox offers Release once for the current message and Always release / Add sender rule for an exact-address rule plus the current message. Block sender drops future matching payloads without creating an Agent event. Nearby addresses are not implicitly approved. Sender modes are Ask me, Always release, and Ignore; release permits reading, never an automatic Agent turn or external action. Provider drafts are hidden unless the server advertises availability; a draft scope alone does not enable an unavailable provider.

Email receiving and Agent processing are separate choices. Disabling processing blocks release and queued delivery to Agents. Automatic Agent email turns remain disabled. Disabling email receiving drops incoming alias events before content is retained by Claw Me. Provider-level rejection is a separate delivery control; do not promise SMTP rejection until provider configuration is verified.

User-facing Page URLs are https://claw.me/@username/page. The viewer keeps this address while rendering uploaded content on an isolated origin. Never serve uploaded HTML on the authenticated application origin.

## Agent-led setup

Account setup is agent-led, with owner portal confirmation for initial account permissions. Later account permission changes are portal-only. A public plugin recipe describing fully portal-free setup does not override this boundary.

With explicit permission to access the owner's personal inbox and act on their
behalf, POST `/api/v1/auth/agent/start` with `email`. This email-only entrypoint
retains email verification and source/target rate limits. Read the newly emailed
Claw Me verification token locally and POST it to `/api/v1/auth/verify-token`.
Use the returned `accessToken` as a temporary owner bearer; verify the email via
`GET /api/v1/auth/me`. Never print tokens or ask for them in chat.

A delegated owner session can approve the exact scope set the owner authorized
at `POST /api/v1/agent-auth/requests/{user_code}/approve`. Exchange the device
secret at `POST /api/v1/agent-auth/requests/{request_id}/token`; that endpoint
returns `api_key`. Keep the scoped key for MCP and discard temporary owner
credentials after setup. Never infer approval from possession of an owner token.
MFA requirements still apply; signup does not require an invitation.

MCP `billing_catalog`, `billing_start_checkout`, and `billing_payment_status`
provide current catalog, hosted Stripe Checkout, and payment/account status.
Checkout requires an `idempotency_key`; reuse it after an uncertain response.
Stripe payment confirmation is separate from webhook-confirmed account activation.
Read the public plugin's portal-free setup reference for the full sequence.

## Native MCP OAuth: authorization code with S256 PKCE

1. Discover the authorization server and protected resource using the URLs above. The canonical resource is https://claw.me/api/v1/mcp.
2. Register a public client at /api/v1/agent-auth/oauth/register with client_name, redirect_uris, grant_types including authorization_code, and token_endpoint_auth_method: none. Redirects must be HTTPS or loopback HTTP.
3. Open /api/v1/agent-auth/oauth/authorize with the returned client_id, exactly registered redirect_uri, response_type=code, code_challenge_method=S256, code_challenge, resource=https://claw.me/api/v1/mcp, state, and scope=onboarding:read for a connection check. Keep the verifier privately in the client.
4. The owner signs in and reviews scopes. The callback preserves state; validate it before exchanging the code.
5. POST form data to /api/v1/agent-auth/oauth/token: grant_type=authorization_code, code, client_id, redirect_uri, code_verifier, and the same resource. Save access_token privately. Never ask for the callback URL or verifier in chat.

Only S256 is supported. Native MCP authorization accepts API scopes, not openid or profile. No client secret or refresh-token grant is advertised. Use the granted scope and expires_in from the token response; owner revocation can end access earlier.

## Device flow

1. Register a public client if needed at /api/v1/agent-auth/oauth/register, then preserve its client_id.
2. POST form data to /api/v1/agent-auth/oauth/device_authorization with client_id and explicit scope=onboarding:read for a connection check. Add login_hint only when the owner supplied their account email.
3. Show verification_uri_complete unchanged as one complete clickable approval link. The owner signs in and reviews access there; do not request a code or emailed sign-in link in chat.
4. Poll /api/v1/agent-auth/oauth/token using grant_type=urn:ietf:params:oauth:grant-type:device_code, the same client_id, and device_code. Respect the returned interval and pending/expired responses. Never exchange a non-OAuth request ID here.
5. Save access_token privately, configure the client, and verify account_get_permissions. Device exchange is single-use.

Device authorization also supports openid and profile for clients that need identity; openid can return an ID token. These are not prerequisites for MCP access and are rejected by native authorization-code MCP grants.

## Supported API scopes

wiki:read, wiki:write, drive:read, drive:propose, pages:read, pages:write, pages:publish, reviews:read, reviews:write, events:read, events:write, channels:read, email:drafts, email:owner, onboarding:read, onboarding:write, setup:read, setup:propose, billing:read, billing:propose, code:execute.

The authorization server additionally advertises openid and profile for the device/OIDC flow. This catalog is not a recommended scope bundle: default to onboarding:read for a read-only connection check. Account feature settings and the owner's actual approved subset still limit every tool. tools/list reports the credential's available tools; public discovery never proves access.