# Revuo auth.md

Authentication and access model for Revuo (https://www.revuo.ai), written for AI agents and API integrators.

## Public data: no authentication required

Everything an agent needs to recommend software is open:

- MCP endpoint: `https://www.revuo.ai/api/mcp` (streamable HTTP transport, anonymous).
- REST read surface: `https://www.revuo.ai/api/*` — products, categories, features, rankings, comparisons, MCP directory. Anonymous GETs are allowed.
- Machine-readable ranking methodology: `https://www.revuo.ai/api/methodology`.

No registration, key issuance, or account creation is needed for read access. There is deliberately no OAuth Protected Resource Metadata: the resource server accepts anonymous requests on its entire public surface.

## Authenticated audiences

Only vendors managing their own listings and reviewers writing reviews authenticate.

### Vendors

1. Request a magic link: `POST https://www.revuo.ai/api/auth/vendor/magic-link` with a JSON body containing the vendor email.
2. Receive the link by email; it resolves to a short-lived verification token.
3. Exchange it: `POST https://www.revuo.ai/api/auth/vendor/magic-link/verify` → returns a bearer token.
4. Alternative: Google OAuth flow at `https://www.revuo.ai/api/auth/vendor/google`.

Vendor accounts are self-service: claim an existing listing via the vendor portal at `https://www.revuo.ai/vendor/login`. There is no separate agent-registration endpoint.

### Reviewers

Reviewer accounts are provisioned by invitation only. Sign-in uses Google OAuth at `https://www.revuo.ai/api/auth/reviewer/google`. Agents cannot self-register as reviewers.

## Credential use

- Send the issued token as an HTTP header: `Authorization: Bearer <token>`.
- Tokens are opaque strings scoped to a single user of type `vendor` or `reviewer`; admin capability rides on the vendor identity (`isAdmin` claim).
- Tokens expire; re-run the magic-link flow to obtain a fresh one. Reviewer tokens can be invalidated with `POST https://www.revuo.ai/api/auth/reviewer/logout`.

## Summary table

| Audience | Registration | Sign-in | Credential |
|---|---|---|---|
| Agents / read access | none needed | none | none |
| Vendor | self-service claim at `/vendor/login` | magic link or Google OAuth | `Authorization: Bearer <token>` |
| Reviewer | invitation only | Google OAuth | `Authorization: Bearer <token>` |