# auth.md

MatchDoku is a timed sudoku game. Agents that need a signed-in player use emailed one-time codes, not a third-party OAuth login screen. Guests can play without an account.

## Audience

Human players and automated agents acting for a player who controls an email inbox.

## Register a guest (anonymous)

No email required. Guest ids are opaque play handles stored in the browser.

```
POST https://matchdoku.com/api/guest
Content-Type: application/json

{}
```

Response includes `guestId`. Send that value as `guestId` on later JSON bodies and query strings when you are not using a bearer token.

## Register or sign in with verified email (OTP)

1. Ask the player for an email address they control.
2. Request a one-time code (valid about 10 minutes):

```
POST https://matchdoku.com/api/auth/otp/request
Content-Type: application/json

{"email": "player@example.com"}
```

3. The player reads the six-digit code from that inbox (or from the UI in local development).
4. Exchange the code for a session token:

```
POST https://matchdoku.com/api/auth/otp/verify
Content-Type: application/json

{"email": "player@example.com", "code": "123456", "guestId": "optional-guest-id"}
```

Response includes `token` and `user`. If you pass `guestId`, guest scores and runs merge into the account.

## Use the credential

Send the token as an HTTP bearer credential:

```
Authorization: Bearer <token>
```

Protected reads include `GET /api/me`. Gameplay routes accept either a bearer token or a `guestId`. Tokens are HS256 JWTs signed by MatchDoku; they are not meant to be verified with a public JWKS.

There is no public client registration, client secret, or authorization-code redirect today. Discovery documents at `/.well-known/oauth-protected-resource` and `/.well-known/oauth-authorization-server` describe this same OTP and guest flow so agents can find the endpoints.

## Revocation

Sign out by dropping the token on the client. Clearing site data removes the guest id. To delete an account, contact MatchDoku using the email on that account (see the Privacy Policy).