User-Delegated OAuth API Access

Let agents request OAuth access from end users via short links, continue working asynchronously, and later claim reusable third-party API tokens from local k...

Security Scan

The skill's declared purpose (an async OAuth handoff using a CLI and local keychain storage) matches what it asks the agent to do and the only external artifact it requires is the clawauth CLI; review of the CLI/package is still recommended before install.

Purpose & Capability

Name/description, the required binary (clawauth), and the included installer metadata all align: this is an OAuth handover helper that expects a preinstalled CLI and an operator-managed install path. No unrelated env vars, binaries, or config paths are requested.

Instruction Scope

Runtime instructions are narrowly scoped to running the clawauth CLI commands (start/status/claim/etc.), parsing JSON, and avoiding token leakage. The skill explicitly forbids running package installs from the agent and warns not to paste tokens to chat/logs. This is coherent, but it relies on the agent/operator to enforce secret-handling rules—accidental token exposure via logs or chat would be a real operational risk.

Install Mechanism

Installer metadata points to an npm package ('clawauth') which is an expected and traceable mechanism for a CLI. npm installs are a moderate-risk install vector; the SKILL.md recommends operator-side preinstallation and pinning. No ad-hoc or unknown URL downloads are instructed by the skill itself.

Credentials

The skill requests no environment variables or credentials in its metadata. The only notable side-effect is that claimed tokens are stored in the local system keychain by the CLI—this is plausible and proportionate to the stated purpose, but requires operators to accept local keychain writes.

Persistence & Privilege

The skill does not request always:true and does not ask to modify other skills or system-wide settings. Autonomous invocation is allowed (platform default) but not combined with other high-privilege requests.

Assessment

This skill is internally consistent for providing an async OAuth handoff via a CLI, but before installing: 1) Review the clawauth npm package and its GitHub source (the SKILL.md points to a repo) and pin an approved version; 2) Ensure the operator pre-installs the CLI into a trusted runtime image (avoid agent-run npm installs); 3) Confirm your runtime's keychain policies and that storing provider tokens locally is acceptable; 4) Make sure agents are configured to never paste CLI output containing tokenData into chat, logs, or telemetry; and 5) If you need higher assurance, run the CLI in an isolated environment and audit its network traffic (it communicates with auth.clawauth.app by default).

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:

npm i -g clawauth

Then verify:

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:

clawauth providers --json

Canonical async flow (non-blocking)

1. Start auth and return immediately:

clawauth login start <provider> --json

2. Extract and forward shortAuthUrl to the user.

3. Continue other work. Do not block.

4. Later poll/check:

clawauth login status <sessionId> --json

5. When status is completed, claim once:

clawauth login claim <sessionId> --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 <seconds>] [--scope <scope>] [--json]
• clawauth login status <sessionId> [--json]
• clawauth login claim <sessionId> [--json]
• clawauth login wait <sessionId> [--timeout <ms>] [--interval <ms>] [--json]

Session management

• clawauth sessions [--json]
• clawauth session-rm <sessionId> [--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

# 1) Start
clawauth login start notion --json

# 2) Share shortAuthUrl with user (from JSON output)

# 3) Later check
clawauth login status <sessionId> --json

# 4) Claim when completed
clawauth login claim <sessionId> --json

# 5) Continue with operator-defined downstream API handling

Reference

See references/commands.md for compact copy-paste command blocks.