# SnapshotFlow auth.md

You are an AI agent. This file tells you how to get an access token for the
SnapshotFlow MCP server (<https://api.snapshotflow.com/mcp>) on behalf of your user,
without the user creating an API key by hand.

- Resource server: <https://api.snapshotflow.com/mcp>
- Authorization server: <https://api.snapshotflow.com>

## 1. Discover

1. `GET` <https://api.snapshotflow.com/.well-known/oauth-protected-resource/mcp> (RFC 9728). It names the authorization server.
2. `GET` <https://api.snapshotflow.com/.well-known/oauth-authorization-server> (RFC 8414). The `agent_auth` object lists the
   endpoints below. If this file and the metadata disagree, the metadata wins.

## 2. Pick a method

SnapshotFlow supports one registration method: `service_auth`. You need your user's email address.
The user must be able to open a link and sign in with Google using that email.

If your MCP client supports the regular OAuth authorization code flow (Claude, Cursor, ChatGPT),
you can use that instead and skip this file.

## 3. Register

```http
POST https://api.snapshotflow.com/agent/identity
Content-Type: application/json

{ "type": "service_auth", "login_hint": "user@example.com", "client_name": "My Agent" }
```

`client_name` is optional and is shown to the user on the approval page.

Response `200`:

```json
{
  "claim_token": "<opaque, keep secret>",
  "claim": {
    "user_code": "WDJB-MJHT",
    "verification_uri": "https://api.snapshotflow.com/agent/claim",
    "verification_uri_complete": "https://api.snapshotflow.com/agent/claim?user_code=WDJB-MJHT",
    "expires_in": 900,
    "interval": 5
  }
}
```

## 4. Claim ceremony

Show the user `verification_uri_complete` (or `verification_uri` and `user_code` together).
The user opens it, checks the code, signs in with Google and approves. SnapshotFlow never emails
the code. The Google account email must match `login_hint`, otherwise the request is denied.

While the user does this, poll the token endpoint no faster than `interval` seconds:

```http
POST https://api.snapshotflow.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Aworkos%3Aagent-auth%3Agrant-type%3Aclaim&claim_token=<claim_token>
```

## 5. Use the access_token

On success you get a standard OAuth token response:

```json
{ "access_token": "...", "token_type": "bearer", "expires_in": 3600, "refresh_token": "...", "scope": "mcp" }
```

Call the MCP server with `Authorization: Bearer <access_token>`. When it expires, refresh with
`grant_type=refresh_token&refresh_token=<refresh_token>&client_id=agent_auth`. The claim token is
single-use and is gone after the first successful exchange.

## 6. Errors

| `error` | Meaning | What to do |
|---|---|---|
| `authorization_pending` | The user has not approved yet | Keep polling every `interval` seconds |
| `slow_down` | You poll too fast | Add 5 seconds to your interval |
| `access_denied` | The user signed in with a different email | Stop, ask the user, register again |
| `expired_token` | The claim expired | Register again |
| `invalid_grant` | Unknown or already used claim token | Register again |
| `unsupported_identity_type` | `type` is not `service_auth` | Use `service_auth` |
| `invalid_request` | Missing or invalid `login_hint` | Send a valid email |

## 7. Revocation

Revoke a token with `POST` <https://api.snapshotflow.com/oauth/revoke> and `token=<access_token or refresh_token>` (RFC 7009).