Document the new sign in method

docs/API.md

@@ -5,6 +5,13 @@ a bot to perform various actions for you.
 
 ## Authentication
 
+There are two ways to authenticate with the Fizzy API:
+
+1. **Personal access tokens** - Long-lived tokens for scripts and integrations
+2. **Magic link authentication** - Session-based authentication for native apps
+
+### Personal Access Tokens
+
 To use the API you'll need an access token. To get one, go to your profile, then,
 in the API section, click on "Personal access tokens" and then click on
 "Generate new access token".
@@ -36,6 +43,81 @@ To authenticate a request using your access token, include it in the `Authorizat
 curl -H "Authorization: Bearer put-your-access-token-here" -H "Accept: application/json" https://app.fizzy.do/my/identity
 ```
 
+### Magic Link Authentication
+
+For native apps, you can authenticate users via magic links. This is a two-step process:
+
+#### 1. Request a magic link
+
+Send the user's email address to request a magic link be sent to them:
+
+```bash
+curl -X POST \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json" \
+  -d '{"email_address": "user@example.com"}' \
+  https://app.fizzy.do/session
+```
+
+__Response:__
+
+```
+HTTP/1.1 201 Created
+Set-Cookie: pending_authentication_token=...; HttpOnly; SameSite=Lax
+```
+
+```json
+{
+  "pending_authentication_token": "eyJfcmFpbHMi..."
+}
+```
+
+The response includes a `pending_authentication_token` both in the JSON body and as a cookie.
+Native apps should store this token and include it as a cookie when submitting the magic link code.
+
+__Error responses:__
+
+| Status Code | Description |
+|--------|-------------|
+| `422 Unprocessable entity` | Invalid email address, if sign ups are enabled and the value isn't a valid email address |
+| `429 Too Many Requests` | Rate limit exceeded |
+
+#### 2. Submit the magic link code
+
+Once the user receives the magic link email, they'll have a 6-character code. Submit it to complete authentication:
+
+```bash
+curl -X POST \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json" \
+  -H "Cookie: pending_authentication_token=eyJfcmFpbHMi..." \
+  -d '{"code": "ABC123"}' \
+  https://app.fizzy.do/session/magic_link
+```
+
+__Response:__
+
+```json
+{
+  "session_token": "eyJfcmFpbHMi..."
+}
+```
+
+The `session_token` can be used to authenticate subsequent requests by including it as a cookie:
+
+```bash
+curl -H "Cookie: session_token=eyJfcmFpbHMi..." \
+  -H "Accept: application/json" \
+  https://app.fizzy.do/my/identity
+```
+
+__Error responses:__
+
+| Status Code | Description |
+|--------|-------------|
+| `401 Unauthorized` | Invalid `pending_authentication_token` or `code` |
+| `429 Too Many Requests` | Rate limit exceeded |
+
 ## Caching
 
 Most endpoints return [ETag](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/ETag) and [Cache-Control](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Cache-Control) headers. You can use these to avoid re-downloading unchanged data.