From 738109844a5d6453a298ece82e23a3eef79c3696 Mon Sep 17 00:00:00 2001 From: Yumechi Date: Tue, 30 Jun 2026 20:30:59 +0800 Subject: [PATCH 1/2] feat: token format redesign --- docs/migrate-to-3.md | 21 +++++++++++++++++++-- 1 file changed, 19 insertions(+), 2 deletions(-) diff --git a/docs/migrate-to-3.md b/docs/migrate-to-3.md index 2780bd9..9f06b5c 100644 --- a/docs/migrate-to-3.md +++ b/docs/migrate-to-3.md @@ -9,6 +9,8 @@ with [`migrate-config`](#migrating-your-config). - If you set list or map environment variables, their syntax changed, see [List and map syntax](#list-and-map-syntax). +- If you rely on the format of tokens or the internal implementation details of token storage, your workflow may need adjusting. + See [token format redesign](#token-format-redesign). - If you have scripts hitting client-token endpoints, they may now need [elevation](#adapting-your-scripts). @@ -78,14 +80,28 @@ GOTIFY_SERVER_RESPONSEHEADERS={"X-Custom-Header":"custom value"} ## API Changes +### Token Format Redesign + +Introduces an EdDSA based token validation scheme to prevent storing plaintext token in database +and create potential for fulfilling more feature requests related to security and authentication. +See [#325](https://github.com/gotify/server/issues/325). + +Tokens for existing applications can now be rotated via the _application security update_ endpoint. + +Existing tokens (starting with `A` and `C`) will continue to work. +Plugin tokens (starting with `P`) used to access web resources are not affected by this change. + +Custom tokens created by manually modifying database entry may cease to work upon upgrading, +in such case please rotate tokens or recreate the corresponding client/application entry. + +### Step-up Authentication + Introduces step-up authentication via time-limited [session elevation](./session-elevation.md). A session/client token must re-authenticate before sensitive, hard-to-undo actions. HTTP Basic auth and application tokens are unaffected. -### Endpoints that now require elevation - With a non-elevated client token these return `403`: | Endpoint | Action | @@ -93,6 +109,7 @@ With a non-elevated client token these return `403`: | `POST /current/user/password` | Change current user's password | | `DELETE /client/{id}` | Delete a client | | `DELETE /application/{id}` | Delete an application | +| `PUT /application/{id}/security` | Application security update | | `POST /client/{id}/elevate` | Elevate a client token | | `GET /user`, `GET`/`POST`/`DELETE /user/{id}` | Manage users (admin) | From 57de2776a6cd5cbc4d27ae01dac42559deb87137 Mon Sep 17 00:00:00 2001 From: Yumechi Date: Wed, 1 Jul 2026 17:00:29 +0800 Subject: [PATCH 2/2] apply suggestions --- docs/migrate-to-3.md | 29 ++++++++++++++++++++++------- 1 file changed, 22 insertions(+), 7 deletions(-) diff --git a/docs/migrate-to-3.md b/docs/migrate-to-3.md index 9f06b5c..038fec4 100644 --- a/docs/migrate-to-3.md +++ b/docs/migrate-to-3.md @@ -83,17 +83,31 @@ GOTIFY_SERVER_RESPONSEHEADERS={"X-Custom-Header":"custom value"} ### Token Format Redesign Introduces an EdDSA based token validation scheme to prevent storing plaintext token in database -and create potential for fulfilling more feature requests related to security and authentication. +and create potential for future authentication methods. See [#325](https://github.com/gotify/server/issues/325). +This also means to align with secure API design principles, +tokens will no longer be returned via the API or WebUI except when the token is issued via creation or rotation. +Workflows dependent on introspecting existing clients or applications for their token will stop working. + +::: tip +The post message endpoint now accepts an "appid" parameter, which allows clients +to impersonate applications they control without knowing the corresponding application token. +::: + Tokens for existing applications can now be rotated via the _application security update_ endpoint. Existing tokens (starting with `A` and `C`) will continue to work. Plugin tokens (starting with `P`) used to access web resources are not affected by this change. -Custom tokens created by manually modifying database entry may cease to work upon upgrading, +Custom tokens created by manually modifying database entries may cease to work upon upgrading, in such case please rotate tokens or recreate the corresponding client/application entry. +Client tokens cannot be rotated at initial release, but this may become possible in the future +without a major version bump. +Workflows should also not assume a one-to-one relationship between tokens and their corresponding entity, +as future versions may include signature-based, scoped, encryption-based and other token-passing methods. + ### Step-up Authentication Introduces step-up authentication via time-limited [session @@ -116,13 +130,14 @@ With a non-elevated client token these return `403`: The `Client` and `CurrentUser` models have gotten elevation-related fields. See the [API documentation](/api-docs) for details. -### Adapting your scripts +::: tip + +To update your workflow that uses the endpoints above with a client token. Perform a separate elevation process before the call. Either: -Scripts that hit the endpoints above with a client token now need that token to -be elevated. Either: +- Transitition to use HTTP Basic auth as they are elevated by default. +- Elevate the client in the WebUI or the api with basic auth before calling these APIs. -- Use HTTP Basic auth as they are elevated by default. -- Elevate the client in the WebUI or the api with basic auth. +::: ## CLI Changes