From 738109844a5d6453a298ece82e23a3eef79c3696 Mon Sep 17 00:00:00 2001 From: Yumechi Date: Tue, 30 Jun 2026 20:30:59 +0800 Subject: [PATCH 1/4] 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/4] 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 From 3bf59ddd57329630decd9d3e309cd83c108c6bfe Mon Sep 17 00:00:00 2001 From: Yumechi Date: Sat, 4 Jul 2026 15:16:10 +0800 Subject: [PATCH 3/4] apply suggestions --- docs/migrate-to-3.md | 14 +------------- 1 file changed, 1 insertion(+), 13 deletions(-) diff --git a/docs/migrate-to-3.md b/docs/migrate-to-3.md index 038fec4..d087079 100644 --- a/docs/migrate-to-3.md +++ b/docs/migrate-to-3.md @@ -82,11 +82,7 @@ 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 future authentication methods. -See [#325](https://github.com/gotify/server/issues/325). - -This also means to align with secure API design principles, +As part of an effort 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. @@ -100,14 +96,6 @@ Tokens for existing applications can now be rotated via the _application securit 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 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 From 1dea350e9c277fec107b2a93cc5e53172998aa15 Mon Sep 17 00:00:00 2001 From: Jannis Mattheis Date: Sat, 4 Jul 2026 15:02:46 +0200 Subject: [PATCH 4/4] fix: update summary and headline --- docs/migrate-to-3.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/migrate-to-3.md b/docs/migrate-to-3.md index d087079..4218148 100644 --- a/docs/migrate-to-3.md +++ b/docs/migrate-to-3.md @@ -9,8 +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). +- API tokens are no longer returned in the GET endpoints and are only exposed + on creation or rotation. See [Tokens are only shown once](#tokens-are-only-shown-once). - If you have scripts hitting client-token endpoints, they may now need [elevation](#adapting-your-scripts). @@ -80,7 +80,7 @@ GOTIFY_SERVER_RESPONSEHEADERS={"X-Custom-Header":"custom value"} ## API Changes -### Token Format Redesign +### Tokens are only shown once As part of an effort 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.