feat: token format redesign

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,34 +80,64 @@ 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 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 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
 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                         |
 | :-------------------------------------------- | :----------------------------- |
 | `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)           |
 
 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