# Auth.md

Agent authentication for RestoSignals. RestoSignals accepts two credentials on the REST API and the MCP server. Both draw on the
same account and credit wallet (1 credit = 1 returned lead).

## Option A: OAuth 2.1 (for MCP clients: Claude, ChatGPT connectors, Cursor, Codex...)
RestoSignals is its own OAuth 2.1 authorization server. No pre-shared secret, no human setup
beyond signing in once.

1. Call the MCP server without a credential: `tools/call` on https://api.restosignals.com/mcp returns HTTP 401 with
   `WWW-Authenticate: Bearer resource_metadata="https://api.restosignals.com/.well-known/oauth-protected-resource"`.
2. Register (RFC 7591 Dynamic Client Registration): `POST https://api.restosignals.com/oauth/register`
   body `{"redirect_uris": ["<your callback>"], "client_name": "<name>"}` → public `client_id`
   (no secret; PKCE protects the code). https callbacks anywhere, http only for loopback.
3. Authorize (PKCE S256): `GET https://api.restosignals.com/oauth/authorize?response_type=code&client_id=...&redirect_uri=...&code_challenge=...&code_challenge_method=S256&state=...`
   The user signs in (or creates a free account, 100 credits) and approves.
4. Token: `POST https://api.restosignals.com/oauth/token` (form-encoded) with `grant_type=authorization_code`,
   `code`, `code_verifier`, `client_id`, `redirect_uri` → `access_token` (Bearer, 1 hour) +
   `refresh_token` (30 days, bound to your client_id). Refresh with `grant_type=refresh_token`.
5. Call `https://api.restosignals.com/mcp` with `Authorization: Bearer <access_token>`.

Scope: `restosignals:read`. Changing the account password revokes every OAuth token.

## Option B: API key (REST, scripts, any MCP client that takes a header)
- Programmatic, no email: `POST https://api.restosignals.com/v1/register` → `{"api_key": "pk_...", "credits": 15}`.
- Full free tier: sign up at https://restosignals.com/signup (100 lead credits, no card), copy the key from the dashboard.
- Send it as `Authorization: Bearer pk_...` or `X-API-Key: pk_...`. Never in a query string.

## No credential needed
The `coverage` MCP tool is free and open, so an agent can check live states before it has any
credential.

## Metering and payment
Empty results are free. With no credits, REST returns HTTP 402 and MCP returns error -32003,
both with an upgrade link (https://restosignals.com/pricing/). Payment is completed by a human there; the
subscription also unlocks owner contact details. Check balance at `GET https://api.restosignals.com/v1/account`.

## Discovery
- Authorization server metadata: https://api.restosignals.com/.well-known/oauth-authorization-server
- Protected resource metadata: https://api.restosignals.com/.well-known/oauth-protected-resource
- MCP server card: https://api.restosignals.com/.well-known/mcp/server-card.json
- llms.txt: https://api.restosignals.com/llms.txt
