diff --git a/docs/migrate-to-3.md b/docs/migrate-to-3.md
index 2780bd9..4218148 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).
+- 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).
 
@@ -78,14 +80,30 @@ GOTIFY_SERVER_RESPONSEHEADERS={"X-Custom-Header":"custom value"}
 
 ## API Changes
 
+### 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.
+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.
+
+### 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,19 +111,21 @@ 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)           |
 
 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