---
name: anyoauth
description: Install and use AnyOAuth to add Google or GitHub sign-in to an application. Use when a user asks to set up AnyOAuth, connect its CLI or MCP server, create or manage AnyOAuth projects, configure callback URLs, or implement and debug an AnyOAuth login flow. Covers browser-based management authentication and secure backend integration for vibe coders and coding agents.
compatibility: Requires Node.js 22 or newer for the CLI/MCP and a browser for account approval.
---

# AnyOAuth

Use the CLI or MCP to create the project, then use the SDK for the application's language to implement sign-in. Read https://anyoauth.com/docs/agents/ for installation and https://anyoauth.com/docs/ for the integration flow.

## 1. Install the tooling

Check `node --version` (22+) and `anyoauth --version`. If the CLI is absent, install the published package:

```sh
npm install --global @anyoauth/cli
anyoauth --help
```

If the initial package has not been published, use the source checkout:

```sh
git clone https://github.com/AnyOAuth/anyoauth.git
```

Run `npm ci` and `npm run tooling:check` in the checkout, then `npm install --global ./packages/cli`. In an existing AnyOAuth checkout, use it directly rather than cloning again.

For an MCP-capable agent, configure a local stdio server:

```json
{
  "mcpServers": {
    "anyoauth": {
      "command": "anyoauth",
      "args": ["mcp"]
    }
  }
}
```

Use the host's MCP configuration format; some hosts use `mcp_servers` instead. The executable is also available as `anyoauth-mcp`. Restart/reconnect the MCP host after configuring it.

## 2. Authenticate through the website

Run `anyoauth login`. It opens the website and displays a device code. Ask the user to sign in with Google or GitHub and approve that matching code. Wait for the CLI to report `authenticated`. The user does not need to copy a token or give the agent a password.

If a browser cannot open, run `anyoauth login --no-browser` and show the returned website URL to the user. For a non-blocking agent workflow, run `anyoauth login --start`, ask the user to approve the code, then `anyoauth login --complete`.

In MCP, call `anyoauth_login`, show the returned `userCode` and `verificationUri`, and ask the user to approve. After approval, call `anyoauth_completeLogin`. A `pending` result means approval has not completed. Do not repeatedly poll while the user is away.

CLI and MCP share origin-scoped local credentials. The management session expires after 30 days; a device request expires after 10 minutes. Run `anyoauth me` or call `anyoauth_me` to verify authentication. Use `anyoauth logout` / `anyoauth_logout` to revoke this installation's access.

## 3. Discover the current methods

Run `anyoauth commands` and `anyoauth <command> --help` before using unfamiliar methods. In MCP, use the server's tool list. Both surfaces are generated from AnyOAuth's JSON schemas, including required fields, array constraints, supported providers, and auth types. Prefer this live discovery over guessing flags or fields.

CLI commands use kebab-case (`create-project`); MCP tools use operation IDs prefixed with `anyoauth_` (`anyoauth_createProject`). CLI field flags use kebab-case; `--json` and `--input` use the schema's original field names.

## 4. Create or reuse a project

Inspect the application's framework, backend, local port, and existing auth routes. Determine its exact callback URL and which implemented providers it needs. List projects first (`anyoauth list-projects` / `anyoauth_listProjects`) to reuse an appropriate project.

For a new project:

```sh
anyoauth create-project --json '{"name":"My app","redirectUris":["http://localhost:3000/auth/callback"],"providers":["google","github"]}'
```

The MCP equivalent is `anyoauth_createProject` with the same JSON fields. The response contains `project.id` and a one-time `clientSecret`. Save these in the application's server-side secret configuration using its established workflow. Do not expose the client secret in browser/mobile code or commit it. Avoid repeating the secret in chat.

Redirects must be exact HTTPS URLs, or HTTP loopback URLs for development; no query, fragment, or credentials. Add the actual production callback with `update-project` / `anyoauth_updateProject`, preserving any existing callbacks and provider choices that should remain: updates replace the full settings.

Only Google and GitHub are currently implemented. `anyoauth providers` / `anyoauth_providers` reports deployment availability. AnyOAuth manages the upstream provider applications, so users do not need to register their own Google/GitHub OAuth apps.

## 5. Implement application sign-in

Use https://anyoauth.com/docs/libraries/ to choose the SDK and its current repository installation instructions. SDK registry publication is separate from source releases; do not guess an install command for an unpublished SDK.

Follow the SDK examples in https://anyoauth.com/docs/:

1. On the backend, generate a fresh random 32-byte base64url private session key. Bind it to the initiating browser via an HttpOnly cookie/server session with a ten-minute expiry and save the exact registered callback. Never place the private key or client secret in URLs or frontend storage.
2. Call backend `createLoginSession` (`POST /v1/login/session`) with sessionKey, provider and redirectUri. Client credentials are supplied by the backend SDK. Navigate the browser to the returned authorization_url; its opaque launch ID cannot retrieve profiles.
3. AnyOAuth returns to the bare registered callback without code/state/error query parameters. Require the original browser cookie, load its original key and callback, and call `loginResult` (`POST /v1/login/result`) from the backend.
4. Pending results are non-consuming and cannot create an app session. Succeeded results contain profile; failed results contain error. Atomically consume the local transaction on terminal results. Use profile.subject as the account key; never merge identities by email. Permit one active pending login per browser.
5. Issue the application's own session and redirect to a clean homepage. Terminal result retrieval is one-time; do not automatically retry ambiguous failures. Start a fresh login instead. Provider tokens, handoff codes, and profile tokens are not exposed in this flow.

Existing authorizationUrl/exchangeCode/profile integrations remain supported for compatibility and require the original browser-bound state and PKCE validation. Do not use the query-bearing legacy flow for new integrations.

Management tokens (`aom_`) are for CLI/MCP project management. Profile tokens (`aop_`) are for application identity lookup. Client secrets (`aosk_`) are for backend code exchange. These credentials are not interchangeable. AnyOAuth does not expose upstream provider tokens or act as a generic OAuth/OIDC authorization server.

## 6. Verify and report

Run the application's typecheck/build and relevant auth checks. Verify exact callback registration, available providers, transaction binding, backend-only secrets, and application-owned sessions. For real sign-in, let the user complete provider authentication in the browser.

Report the project ID, callbacks, providers, changed integration files, checks run, and any remaining deployment steps. Keep one-time secrets and saved management tokens out of that report. Use generated errors/help to diagnose issues; reauthenticate on an expired management session.