diff --git a/README.md b/README.md
index a57e5d9..35d8d85 100644
--- a/README.md
+++ b/README.md
@@ -178,46 +178,79 @@ metadata.json
 
 An HTTP wrapper (`app.py` + `bgfilter/service.py`) exposes the pipeline as a
 long-running FastAPI service. Models load once and are reused across requests.
-For deploying to a Linux server (dependencies, weights, systemd, offline mode), see
-[DEPLOY.md](DEPLOY.md).
-
-```powershell
-D:\MiniConda\envs\lightML\python.exe -m uvicorn app:app `
-  --host 127.0.0.1 --port 18083 --workers 1
-```
-
-Two endpoints:
-
-- `GET /healthz` — liveness/config JSON.
-- `POST /remove-background` — `multipart/form-data`, returns `image/png`.
-  - `file` (required) — the source image. The field name is fixed as `file`.
-  - `screen_color` (optional) — `#RRGGBB` prior; omit/empty for auto-detect.
-  - `seg_model` (optional) — `birefnet` (default) or `anime-seg`.
-  - `cross_check` (optional) — `1`/`0` (also `true`/`false`/`yes`/`no`/`on`/`off`);
-    per-request override of the cross-model veto. Omit/empty to use the service
-    default. The response reports the effective state in `X-BGFilter-Cross-Check`.
+For deploying to a Linux server (dependencies, weights, systemd, offline mode, auth),
+see [DEPLOY.md](DEPLOY.md).
 
 ```bash
-# default (birefnet + auto background colour)
+python -m uvicorn app:app --host 127.0.0.1 --port 18083 --workers 1
+```
+
+Run a single worker (`--workers 1`) — each worker loads its own copy of the models.
+
+### Endpoints
+
+- **`GET /healthz`** — liveness + config JSON, e.g.
+  `{"ok":true,"service":"bgfilter","version":"0.1.0","defaultSegModel":"birefnet","device":"cpu","crossCheck":true}`.
+  Always unauthenticated.
+- **`POST /remove-background`** — `multipart/form-data` in, `image/png` (RGBA) out.
+
+### Authentication
+
+Optional, opt-in via the `BGFILTER_AUTH_TOKEN` env var. When set, `/remove-background`
+requires header **`X-Genarrative-Image-Token: <token>`** (constant-time compare); a
+missing or wrong token returns `401`. When unset the endpoint is open (a fronting proxy
+is expected to authenticate). `/healthz` is always open. See [DEPLOY.md](DEPLOY.md) §10.
+
+### Request fields (`POST /remove-background`, `multipart/form-data`)
+
+| Field | Required | Values | Meaning |
+| --- | --- | --- | --- |
+| `file` | yes | image file | Source image (field name fixed as `file`). |
+| `screen_color` | no | `#RRGGBB`, or omit/empty/`auto` | Background-colour prior; omit to auto-detect from the border. |
+| `seg_model` | no | `birefnet` (default) / `anime-seg` | Segmentation backend. |
+| `cross_check` | no | `1`/`0` (also `true`/`false`/`yes`/`no`/`on`/`off`) | Per-request override of the cross-model veto; omit/empty = service default. |
+
+### Response headers (on `200`)
+
+| Header | Example | Meaning |
+| --- | --- | --- |
+| `X-BGFilter-Elapsed-Ms` | `2372` | Server-side processing time (ms). |
+| `X-BGFilter-Seg-Model` | `birefnet` | Segmenter actually used. |
+| `X-BGFilter-Screen-Color` | `#CFEFFF` / `auto` | Background colour used. |
+| `X-BGFilter-Cross-Check` | `on` / `off` | Effective cross-check state. |
+
+### Status codes
+
+| Code | When |
+| --- | --- |
+| `200` | Success — body is the RGBA PNG. |
+| `400` | Bad input: unreadable image, invalid `screen_color`/`seg_model`/`cross_check`, or auto-detect failed (pass `screen_color`). |
+| `401` | Auth enabled and the token is missing or wrong. |
+| `413` | Image exceeds `BGFILTER_MAX_IMAGE_PIXELS` (~4 MP by default). |
+| `500` | Inference failed. |
+| `503` | Service still loading models (not ready). |
+
+### Examples
+
+```bash
+# default (birefnet + auto background colour); add the auth header if the service requires it
 curl -sS -F "file=@input.png" \
+  -H "X-Genarrative-Image-Token: <token>" \
   http://127.0.0.1:18083/remove-background -o output.png
 
-# explicit background colour + anime segmenter
+# explicit background colour + anime segmenter, cross-check off for this request
 curl -sS \
   -F "file=@input.png" \
   -F "screen_color=#CFEFFF" \
   -F "seg_model=anime-seg" \
-  http://127.0.0.1:18083/remove-background -o output.png
-
-# enable the cross-model veto for this request only (see below; slow on CPU)
-curl -sS -F "file=@input.png" -F "cross_check=1" \
+  -F "cross_check=off" \
   http://127.0.0.1:18083/remove-background -o output.png
 ```
 
 Config comes from `BGFILTER_CONFIG` (defaults to `configs/default.yaml` when present);
 `BGFILTER_DEVICE` overrides both model and segmentation device; `BGFILTER_MAX_IMAGE_PIXELS`
 caps input size (default ~4MP → `413`); `BGFILTER_PRELOAD=1` loads the default models at
-startup. Run a single worker (`--workers 1`) — each worker loads its own copy of the models.
+startup; `BGFILTER_AUTH_TOKEN` gates the endpoint (see Authentication above).
 
 Like the CLI, the service runs the **cross-model veto by default** (config
 default: on); its HR-matting model is preloaded with the rest of the warm set.