# Fevori auth.md

How an AI agent gets access to a person's Fevori account. Fevori sends personal party invitations by email and tracks RSVPs. Agents use it through the REST API (https://fevori.app/api/v1) or the MCP server (https://fevori.app/mcp). Full reference: https://fevori.app/docs/api.

## Pick a method

1. **Your person is here:** use OAuth (below), for MCP at https://fevori.app/mcp or the REST API at https://fevori.app/api/v1. Best: no secrets to copy, and they choose what you may do.
2. **Your person can give you a key:** they create one at https://fevori.app/account. Send it as `Authorization: Bearer fev_…`. It works for both the REST API and MCP, with full access.
3. **No person yet:** register an agent account yourself (below), work on drafts, and hand your person a claim link.

## OAuth

There are two protected resources, each with its own tokens:

- **MCP server**, resource `https://fevori.app/mcp`, metadata at https://fevori.app/.well-known/oauth-protected-resource/mcp.
- **REST API** (https://fevori.app/api/v1), resource `https://fevori.app`, metadata at https://fevori.app/.well-known/oauth-protected-resource.

- Discover: a request without a token returns `401` with `WWW-Authenticate: Bearer resource_metadata="…"` naming the resource's metadata. Both name the authorization server, https://fevori.app, whose metadata is at https://fevori.app/.well-known/oauth-authorization-server.
- Register: Client ID Metadata Documents (an HTTPS `client_id`) or dynamic client registration at https://fevori.app/oauth/register.
- Authorize: authorization code with PKCE (S256) at https://fevori.app/oauth/authorize, with `resource` set to the one you want (`https://fevori.app/mcp` if you leave it out). The person signs in with Google and picks permissions.
- Tokens: https://fevori.app/oauth/token. Access tokens last an hour; refresh tokens rotate.
- Scopes:
- `events:read`: see your events, guest lists and rsvps.
- `events:write`: create, change and delete events and guests.
- `invitations:send`: email invitations to your guests in your name.
- A tool or request that needs a scope you don't have answers `403` with `error="insufficient_scope"` and the scopes to ask for; re-authorize with them. On the REST API, reads need `events:read`, changes `events:write`, and sending invitations `invitations:send`.

## Register an agent account (no person yet)

```
POST https://fevori.app/api/v1/accounts
Content-Type: application/json

{"name": "Who you are, shown to the person who claims it"}
```

Response (`201`):

```json
{"api_key": "fev_…", "claim_url": "https://fevori.app/claim/…", "account": {"id": "agt_…", "name": "…", "claimed": false, "expires_at": "…"}}
```

- The `api_key` is shown once. Use it as `Authorization: Bearer <api_key>` on the REST API or MCP.
- Until claimed you can create draft events and guest lists (up to 25 events). Publishing and sending invitations return `403` with code `account_unclaimed` and the `claim_url`.
- No credentials or email are needed to register. It's rate limited per IP address.
- Unclaimed accounts are deleted after 30 days, with their events.

## Claim

Give your person the `claim_url` (or have them open https://fevori.app/claim and paste it there). They open it, sign in with Google, and confirm. The account's events move into their Fevori account (new or existing), and **your same API key now acts as their account**: you can publish and send. `GET https://fevori.app/api/v1/me` reports `"claimed": true` once it's done.

## Use the credential

Send `Authorization: Bearer <token or key>` on every request. Cookies are never used for the API or MCP.

## Errors

- `401`: missing, unknown, expired or revoked credential.
- `403 account_unclaimed`: give your person the `claim_url`.
- `403 insufficient_scope` (MCP, OAuth): re-authorize with the scopes named.
- `429 rate_limited`: too many agent accounts from this address; wait a minute.

## Revocation

People revoke API keys and disconnect OAuth apps at https://fevori.app/account. OAuth clients can revoke their own tokens at https://fevori.app/oauth/token (RFC 7009).

## Metadata

https://fevori.app/.well-known/oauth-authorization-server carries an `agent_auth` block (the field names isitagentready.com's auth.md check uses): `register_uri` is the registration endpoint above, `claim_uri` the claim page, `identity_types_supported` is `anonymous`, and the credential is an `api_key`. The flow is Fevori's own, as described here; it is not WorkOS's auth.md protocol (no identity assertions or claim tokens).