# 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 authorization server: the resource server accepts anonymous requests on its entire public surface.

**Do not request a magic link.** Magic-link mail is a mailbox challenge for human vendors. Placeholder addresses (`@example.com`, `@example.org`, `.invalid`, `.test`) are discarded. There is no agent-registration endpoint.

## Authenticated audiences

Only vendors managing their own listings and reviewers writing reviews authenticate. Both are human flows.

### Vendors

Human vendors sign in at `https://www.revuo.ai/vendor/login` (Google OAuth or a magic link sent to a real work mailbox they can read). After sign-in, API calls use `Authorization: Bearer <token>`.

Vendor accounts are self-service: claim an existing listing via that portal. There is no separate agent-registration endpoint, and agents cannot obtain a vendor token without receiving email at a real mailbox.

### 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; a human vendor re-runs the sign-in flow at `/vendor/login` to obtain a fresh one. Reviewer tokens can be invalidated with `POST https://www.revuo.ai/api/auth/reviewer/logout`.

## Machine-readable discovery

- Protected Resource Metadata (RFC 9728): `https://www.revuo.ai/.well-known/oauth-protected-resource`.
- Every API 401 carries `WWW-Authenticate: Bearer resource_metadata="..."` pointing there, so agents can discover this document programmatically.
- Revuo does not run an OAuth authorization server — credentials are issued through the human flows above; `authorization_servers` is therefore absent from the metadata document.

## 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 (human) | `Authorization: Bearer <token>` |
| Reviewer | invitation only | Google OAuth | `Authorization: Bearer <token>` |