# auth.md

You are an agent. This is how to act for a person on MakerRadar: discover → pick a method → register → the person claims you → call the API → handle revocation. Follow the steps in order.

Most of MakerRadar needs no credential at all. Searching products, reading a listing, alternatives, comparisons and launch weeks, and drafting a listing for a person to submit, are open over MCP (https://api.makerradar.io/mcp) and REST (https://api.makerradar.io/v1), no key and no registration. You need a token only to act for a person: their listings, launches and checkouts.

## Step 1 — Discover

- Protected resource metadata (RFC 9728): https://api.makerradar.io/.well-known/oauth-protected-resource (for the MCP endpoint that needs an account: https://api.makerradar.io/.well-known/oauth-protected-resource/mcp/account).
- Authorization server metadata (RFC 8414): https://api.makerradar.io/.well-known/oauth-authorization-server. The issuer is `https://api.makerradar.io`; its `agent_auth` block points back to this page.
- A call to https://api.makerradar.io/mcp/account without a token answers 401 with `WWW-Authenticate: Bearer resource_metadata="…"`.

## Step 2 — Pick a method

1. **Your client has a Connect button or is an OAuth client** (Claude, ChatGPT, Cursor, VS Code connectors) → Step 3a, OAuth with PKCE.
2. **You can show the person a link and a short code** → Step 3b, a connect code. This is the `anonymous` registration in the `agent_auth` block: you assert no identity, and the person claims you.
3. **You only need public data** → stop here; call the API without a token.

MakerRadar takes no identity assertions (ID-JAG) and no email login hint: a person always approves an agent themselves, signed in on https://makerradar.io/.

## Step 3a — OAuth 2.1 with PKCE

1. Register: `POST https://api.makerradar.io/oauth/register` (RFC 7591) with `client_name` and `redirect_uris` — or use a Client ID Metadata Document URL as your `client_id`.
2. Send the person to https://makerradar.io/oauth/authorize with `response_type=code`, `client_id`, `redirect_uri`, `code_challenge` (S256), `state`, `scope` and `resource=https://api.makerradar.io/mcp/account`.
3. Trade the code at `POST https://api.makerradar.io/oauth/token` (`grant_type=authorization_code` with your `code_verifier`). You get an access token (`mr_…`) and a refresh token (`mrr_…`); refresh with `grant_type=refresh_token`.
4. No browser redirect? The same client can use the device grant (RFC 8628): `POST https://api.makerradar.io/oauth/device_authorization`, show the person `verification_uri_complete`, then poll the token endpoint with `grant_type=urn:ietf:params:oauth:grant-type:device_code`.

## Step 3b — A connect code

1. Register: `POST https://api.makerradar.io/v1/agent/connect` with JSON `{"client": "<your name, as the person should see it>"}` (or MCP `connect_account`). The answer's `data` has `userCode`, `verificationUri`, `verificationUriComplete`, your secret `deviceCode`, `interval` and `expiresIn`.
2. The person claims you: show them `verificationUriComplete` (or https://makerradar.io/connect and `userCode`). They sign in, see what you're asking for, and approve. Never show them `deviceCode`.
3. Every `interval` seconds, `POST https://api.makerradar.io/v1/agent/token` with `{"deviceCode": "…"}` (or MCP `connect_account_finish`). `pending` means ask again; `approved` carries your token, shown once; `denied` and `expired` mean start over.

## Step 4 — Call the API

Send `Authorization: Bearer <token>` to https://api.makerradar.io/mcp/account (MCP) and https://api.makerradar.io/v1/me and the rest of `/v1/me` (REST). `get_my_account` says who you act for and which scopes you hold. A 403 with `error="insufficient_scope"` names the scopes to ask for.

Scopes:

- `listings:read`: See your listings and where they stand.
- `listings:write`: Add listings and edit them (on a live listing, big changes wait for review).
- `launches:write`: Choose a launch week and send a listing for review.
- `billing:checkout`: Start checkouts for you to pay yourself, and see your orders.

## Step 5 — Revocation

- The person can revoke you at any time in Dashboard › AI agents (https://makerradar.io/dashboard/developer). Your next call answers 401: start again at Step 2.
- An OAuth client revokes its own tokens at `POST https://api.makerradar.io/oauth/revoke` (RFC 7009).
- A connect-code token works for 90 days; an OAuth client's is refreshed for as long as it's used.

## Limits

- No scope votes, comments, reviews or changes the person's account.
- You can start a checkout (`start_checkout`), never pay: the person pays on the page it returns.
- Listings are reviewed before they go live. More: https://makerradar.io/mcp.