# OghmaNotes auth.md

Start registration for a new user. The user must approve it and prove email ownership. This does not grant the agent account or API access.

## Start registration

`POST https://oghmanotes.ie/agent/identity`

```json
{ "type": "service_auth", "login_hint": "student@example.com" }
```

The email must be new. Response:

```json
{
  "claim_token": "…",
  "claim": {
    "user_code": "123456",
    "verification_uri": "https://oghmanotes.ie/register?agent_claim_token=…"
  }
}
```

Give the user `claim.verification_uri` and `claim.user_code`. They finish with matching verified Google/GitHub OAuth, or password plus email link.

Poll no more than every five seconds: `POST https://oghmanotes.ie/agent/identity/claim` with `{ "claim_token": "…" }`.

Claims expire after 15 minutes. Never request or receive the user's password, OAuth token, cookie, or verification link. A verified claim proves registration only; it is not an API credential.