# Agent authentication for Reaudit

This document tells an AI agent how to connect to Reaudit on behalf of a user.

## If a user asked you to connect to Reaudit — DO THIS NOW

Do **not** tell the user to get an API key or edit config files unless OAuth fails.

### Codex CLI (preferred)

You MUST run these commands yourself in the terminal (do not ask the user to copy them):

```bash
codex mcp add reaudit --url https://mcp.reaudit.io/mcp
codex mcp login reaudit
```

This opens OAuth in the browser. Tell the user: "A browser window should open — sign in to Reaudit and click Authorize." Wait for them to complete authorization, then run `codex mcp list` to confirm reaudit is authenticated. Offer to call `list_projects`.

If login fails: `codex mcp logout reaudit` then retry `codex mcp login reaudit`.

After OAuth, tools may appear on the next turn — ask the user to say "list my Reaudit projects" or run `/mcp` to refresh.

### Other clients

- **Claude.ai / ChatGPT:** Add connector `https://mcp.reaudit.io/mcp` → OAuth in the UI (one-click)
- **Claude Code:** `claude mcp add --transport http reaudit https://mcp.reaudit.io/mcp` then OAuth login when prompted
- **Cursor:** `cursor mcp add reaudit https://mcp.reaudit.io/mcp` (OAuth) — use API key + mcp-remote only if OAuth fails

Human fallback: <https://reaudit.io/connect>

---

Reaudit is a paid product. **Connecting an agent does not create a free
account.** An agent acts on behalf of an existing Reaudit account that already
has an active subscription. The human owner authorizes the agent through a
standard OAuth 2.0 consent flow, and every API call remains scoped to that
account's plan and limits. Access is delegated and can be revoked at any time.

If you do not yet have a Reaudit account, purchase a plan at
<https://reaudit.io/pricing> first. Agent-initiated purchasing is also
available via the Agentic Commerce Protocol — see
<https://reaudit.io/.well-known/acp.json>.

## Endpoints

All endpoints are OAuth 2.0 with PKCE (RFC 6749 + RFC 7636). Discovery metadata
is published at:

- Authorization server metadata: <https://reaudit.io/.well-known/oauth-authorization-server>
- Protected resource metadata: <https://mcp.reaudit.io/.well-known/oauth-protected-resource>
- MCP server card: <https://reaudit.io/.well-known/mcp/server-card.json>

| Purpose | Endpoint |
| --- | --- |
| Dynamic client registration (RFC 7591) | `POST https://reaudit.io/api/oauth/register` |
| Authorization | `GET https://reaudit.io/api/oauth/authorize` |
| Token | `POST https://reaudit.io/api/oauth/token` |
| Revocation | `POST https://reaudit.io/api/oauth/revoke` |
| Introspection | `POST https://reaudit.io/api/oauth/introspect` |

## Flow

1. **Register the client** (optional). `POST /api/oauth/register` with a
   `client_name` and `redirect_uris` to obtain a `client_id`. This registers the
   agent application only — it grants no data access on its own.
2. **Authorize.** Send the user to `GET /api/oauth/authorize` with
   `client_id`, `redirect_uri`, `response_type=code`, `state`, and a PKCE
   `code_challenge` (`S256`). The user must be signed in to a Reaudit account
   with an active subscription and approve the consent screen.
3. **Exchange the code.** `POST /api/oauth/token` with the authorization code
   and PKCE `code_verifier` to receive an access token (and refresh token).
4. **Call the API.** Use the access token as a Bearer token against the MCP
   server at `https://mcp.reaudit.io/mcp` (Streamable HTTP). Calls are
   subscription-gated to the authorizing account.
5. **Revoke** any time via `POST /api/oauth/revoke`.

## Identity and credentials

- Supported identity types: `human-delegated` (a human authorizes the agent).
- Supported credential types: `oauth2_authorization_code` with PKCE; refresh
  tokens for long-lived access.
- Scopes: `full_access`.

There is no machine-only / unattended registration that bypasses a human and a
paid subscription.