From 3e01c2965798708978c9f10080537bb7017d6523 Mon Sep 17 00:00:00 2001 From: Florian Sylvain Date: Mon, 5 Oct 2026 02:08:26 +0200 Subject: [PATCH] release: v2.8.0-beta API keys and API reference --- docs/release-notes.md | 1 + docs/releases/v2.8.0-beta.md | 41 ++++++++++++++++++++++++++++++++++++ 2 files changed, 42 insertions(+) create mode 100644 docs/releases/v2.8.0-beta.md diff --git a/docs/release-notes.md b/docs/release-notes.md index 9bce210..274d32c 100644 --- a/docs/release-notes.md +++ b/docs/release-notes.md @@ -30,3 +30,4 @@ Each body lives in `docs/releases/.md`. Publish with `tea releases create - | `v2.6.0-beta` | v2.6.0-beta - Signed updates and browser restart | | `v2.6.2-beta` | v2.6.2-beta - English and French interface | | `v2.7.0-beta` | v2.7.0-beta - Markdown and block article bodies | +| `v2.8.0-beta` | v2.8.0-beta - API keys and API reference | diff --git a/docs/releases/v2.8.0-beta.md b/docs/releases/v2.8.0-beta.md new file mode 100644 index 0000000..ec4a16d --- /dev/null +++ b/docs/releases/v2.8.0-beta.md @@ -0,0 +1,41 @@ +This release adds API keys, so a script or service can use the whole API without the web interface, and turns the Integration page into a complete API reference. + +## New + +**API keys** + +- Create named API keys from the new API keys screen under Integration, with an optional expiry date. The full key is shown once, when you create it, and only its prefix is visible afterwards. +- Send a key as `Authorization: Bearer rcms_...` to manage articles, media, users and invites, and to read settings. A key acts with exactly the rights of the user who created it, so an admin's key cannot do owner-only things. +- Revoke a key at any time. Active, expired and revoked keys all stay listed with their status, creation date and last use. +- The owner sees every key and who created it. Admins see only their own. +- Each key is limited to 120 requests per minute. +- Resetting a user's password revokes all of that user's keys. + +**API reference** + +- The Integration page now documents every route a developer can call, grouped by area: articles, media, users and invites, and settings. Each endpoint lists who can call it, its request body, ready-to-copy fetch and curl examples, a sample response and its error statuses. +- A new Authentication section explains public access and API keys, and a section index lets you jump between groups. +- Routes that need a signed-in browser session are listed separately, and the page shows the real error messages the API returns. +- The Integration page and the API keys screen are available in English and French. + +## API + +- `POST /v1/api-key` creates a key. It answers `201` with the key, shown once. +- `GET /v1/api-key` lists keys, newest first, each with a `status` of `active`, `expired` or `revoked`. For the owner, each entry also carries `created_by_name`. +- `DELETE /v1/api-key/{id}` revokes a key and answers `204`, also when the key is already revoked. +- An invalid, unknown, expired or revoked key answers `401` on every route, including public ones, and is never treated as anonymous. +- A key calling a session-only route answers `403` with "This action needs a real session." These routes are `/v1/api-key`, `POST /v1/auth/verify`, `DELETE /v1/auth/register` and everything under `/v1/system`. +- `GET /v1/auth/me` accepts an API key, so a client can check who a key belongs to. +- A key beyond 120 requests per minute gets `429` with a `Retry-After` header. +- Cross-origin requests now allow the `PATCH` method. + +## Under the hood + +- Add the API key domain, use cases, SQLite repository and an authentication middleware that runs after each token verifier. Keys are generated by a new domain interface and stored as SHA-256 hashes, never in clear. +- Add a typed API catalogue that drives the Integration page, with a test that every route has a description. +- Add the API keys and Integration specifications and QA procedures to `features/`, and the API key reference to `docs/api/`. + +## Upgrading + +- Replace the binary. The new API keys table is created automatically at startup. No new environment variable is required. +- Browsers calling the API from another origin can now use `PATCH`. Check your CORS configuration only if you restricted methods in a reverse proxy.