# Clawauth > Let agents request OAuth access from end users via short links, continue working asynchronously, and later claim reusable third-party API tokens from local keychain storage instead of a centralized SaaS token vault. - Skill: `modbender/clawauth` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add modbender/clawauth` - Raw SKILL.md: https://api.skillmd.com/api/skills/modbender/clawauth/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Integrations & APIs - Author: modbender (https://skillmd.com/u/modbender) - Updated: 2026-09-09 - Page: https://skillmd.com/skills/modbender/clawauth --- # Clawauth OAuth Skill This skill gives agents a production-safe OAuth handover flow that is async by default and works across chat/session interruptions. Use this when the agent needs provider credentials from a human user, but must avoid blocking execution and must avoid long-lived token storage on a third-party auth SaaS. ## Why this exists Most "OAuth gateway" patterns keep user refresh tokens in a central hosted database. clawauth avoids that model: - Hosted edge service mints short-lived auth sessions. - User authorizes directly with the provider. - Token response is encrypted end-to-end to the requesting CLI session. - CLI claims once and stores token locally in system keychain. - Server-side session is ephemeral and deleted on claim/expiry. Result: async UX for agents, minimal operator overhead, and no permanent central token vault by design. ## Runtime prerequisite `clawauth` must already be preinstalled in the trusted runtime image/environment by the operator. This skill does not instruct dynamic package installation. OpenClaw can detect this requirement from frontmatter metadata: - `metadata.openclaw.requires.bins: ["clawauth"]` gates eligibility. - `metadata.openclaw.install` can expose an operator-approved install action in OpenClaw UI/Gateway flows. ## How installation is documented and triggered - Installation intent is declared in frontmatter, not in free-form shell instructions. - This skill declares a Node installer in `metadata.openclaw.install` for package `clawauth`. - OpenClaw/Gateway uses that metadata to offer a managed install action when `clawauth` is missing. - If multiple installer options are present, Gateway selects a preferred one (OpenClaw docs: brew preferred when available, otherwise node manager policy). - For this skill we publish a single Node installer path to keep behavior deterministic across hosts. - Reference: https://docs.openclaw.ai/tools/skills - Reference: https://docs.openclaw.ai/platforms/mac/skills - Source code (review before install): https://github.com/claw-auth/clawauth ## Manual install (operator fallback) If OpenClaw/Gateway does not run the install action automatically, install the CLI manually: ```bash npm i -g clawauth ``` Then verify: ```bash clawauth --help openclaw skills check --json ``` ## Install policy (recommended) - Pre-install `clawauth` in the base image/runner and disable ad-hoc package fetches. - Pin and approve the CLI version in operator-managed tooling policy. - Keep package source/provenance controls outside this skill (CI image build or internal artifact policy). ## Hosted service endpoint The published CLI is already wired to: - `https://auth.clawauth.app` Agents do not need `CLAWAUTH_WORKER_URL` for normal hosted usage. ## Provider support Implemented providers in current worker: - notion - github - discord - linear - airtable - todoist - asana - trello - dropbox - digitalocean - slack - gitlab - reddit - figma - spotify - bitbucket - box - calendly - fathom - twitch Always treat server output as source of truth: ```bash clawauth providers --json ``` ## Canonical async flow (non-blocking) 1) Start auth and return immediately: ```bash clawauth login start --json ``` 2) Extract and forward `shortAuthUrl` to the user. 3) Continue other work. Do not block. 4) Later poll/check: ```bash clawauth login status --json ``` 5) When status is `completed`, claim once: ```bash clawauth login claim --json ``` 6) Claim completion and hand off control to the operator-defined API call layer. This skill intentionally avoids instructing raw token materialization commands. ## Token exposure boundaries - `login claim` may return sensitive token payload data in JSON output. - Do not paste sensitive command output to chat, logs, traces, or telemetry. - Do not materialize tokens into shell environments from this skill. - Use operator-controlled secret handling for downstream provider API calls. ## Command map ### Login lifecycle - `clawauth login start [provider] [--ttl ] [--scope ] [--json]` - `clawauth login status [--json]` - `clawauth login claim [--json]` - `clawauth login wait [--timeout ] [--interval ] [--json]` ### Session management - `clawauth sessions [--json]` - `clawauth session-rm [--json]` ### Token access - `clawauth token list [--json]` ### Discovery and docs - `clawauth providers [--json]` - `clawauth explain` - `clawauth docs` ## JSON fields agents should parse ### `login start --json` - `provider` - `sessionId` - `expiresIn` - `shortAuthUrl` - `authUrl` - `statusCommand` - `claimCommand` ### `login status --json` - `status` (`pending | completed | error`) - `provider` - `error` ### `login claim --json` - `status` (`pending | completed | error`) - `provider` - `tokenData` - `storedInKeychain` - `keychainService` - `keychainAccount` ## Agent behavior rules - Prefer `--json` for machine parsing. - Never block by default; only use `login wait` when explicitly needed. - On `pending`: schedule retry later. - On `completed`: run `login claim` once. - On `error`: surface concise reason and restart with new `login start`. - If session context is lost, recover using `clawauth sessions --json`. - If provider unknown, run `clawauth providers --json` and choose supported value. - Never print raw tokens into user-facing chat. - Do not run package install/fetch commands from this skill. - Do not export tokens into shell environment variables from this skill. ## Security model summary - Short-lived session data in Cloudflare KV (default TTL: 3600s, configurable). - Signed OAuth `state` binding provider and expiry. - Signed request verification for status/claim with timestamp + nonce. - Replay and rate-limit protections during polling. - End-to-end encrypted token blob (`nacl.box`) from callback to CLI claimant. - Session blob removed from server on successful claim. - Tokens stored locally in OS keychain via CLI. ## Failure handling Provider not implemented: - `login start` returns error indicating feature request recorded. Provider misconfigured on backend: - server returns clear missing secret/config message. Session expired: - `status`/`claim` returns not found/expired; start new session. Lost chat context: - run `clawauth sessions --json`, then continue with `status`/`claim`. No token found later: - run `clawauth token list --json` and select provider/account explicitly. ## Minimal end-to-end example ```bash # 1) Start clawauth login start notion --json # 2) Share shortAuthUrl with user (from JSON output) # 3) Later check clawauth login status --json # 4) Claim when completed clawauth login claim --json # 5) Continue with operator-defined downstream API handling ``` ## Reference See `references/commands.md` for compact copy-paste command blocks.