Document AMQP 1.0 token renewal

Docs for rabbitmq/rabbitmq-server#12599

Author: ansd

docs/amqp.md

@@ -281,10 +281,9 @@ This section lists features that RabbitMQ supports exclusively in AMQP 1.0, whic
 This section lists features that RabbitMQ supports exclusively in AMQP 0.9.1, which are currently not available in AMQP 1.0:
 * **[Transactions](./semantics)**: AMQP 0.9.1 provides limited support, whereas AMQP 1.0 currently does not support transactions (as listed in the [limitations](#limitations)).
 * **[Direct Reply-to](./direct-reply-to)**: While AMQP 1.0 clients can still perform Remote Procedure Calls (RPCs) by declaring a reply queue, the Direct Reply-to feature is exclusive to AMQP 0.9.1.
-* **[OAuth 2.0 Token Refresh](./oauth2#token-expiration)**: AMQP 0.9.1 clients can renew tokens via method [update-secret](/amqp-0-9-1-reference#connection.update-secret). Token renewal is currently unsupported in AMQP 1.0. When a token expires, the AMQP 1.0 connection will be closed.
 * **[AMQP 0.9.1 Channel Interceptor](https://github.com/rabbitmq/internals/blob/master/interceptors.md)**: Plugins, such as the [Sharding Plugin](https://github.com/rabbitmq/rabbitmq-server/tree/main/deps/rabbitmq_sharding#rabbitmq-sharding-plugin), that intercept and modify frames are [currently](https://github.com/rabbitmq/rabbitmq-server/issues/10051) only supported for AMQP 0.9.1.
-* **Metrics delivery including message rates via the Management UI**: As documented in the [Deprecation Announcements](/blog/2021/08/21/4.0-deprecation-announcements#disable-metrics-delivery-via-the-management-api--ui), [Prometheus](./prometheus) should be used.
 * **Inspecting AMQP 0.9.1 Channel Details**: This can be done [in the Management UI](./channels#inspect-in-management-ui) or [using CLI tools](./channels#inspect-using-cli-tools). AMQP 1.0 session and link details currently cannot be inspected.
+* **Message rates in the Management UI**
 
 ### Clients
 

docs/oauth2.md

@@ -365,11 +365,17 @@ When verification is enabled, this `aud` field must either match the `resource_s
 
 ### Token expiration and refresh {#token-expiration}
 
-On an existing connection, the token can be refreshed by the [update-secret](/amqp-0-9-1-reference#connection.update-secret) AMQP 0.9.1 method.
-Please check your client whether it supports this method (for example documentation for the [Java client](/client-libraries/java-api-guide#oauth2-refreshing-token)).
-Otherwise the client has to disconnect and reconnect to use a new token.
+In RabbitMQ, token expiration and refresh processes vary between AMQP 1.0 and AMQP 0.9.1 protocols.
 
-If the latest token expires on an existing connection, after a limited time the broker will refuse all operations (but it won't disconnect).
+For **AMQP 1.0**, if the latest token on an existing connection expires, RabbitMQ disconnects the client.
+To prevent disconnection, the client should proactively refresh the token before it expires.
+The client can set a new token by sending an [HTTP over AMQP 1.0](https://github.com/oasis-tcs/amqp-specs/blob/master/http-over-amqp-v1.0-wd06a.docx) request.
+This request should use a `PUT` operation to the `/auth/tokens` endpoint, with the token included in the body as a [binary](https://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-types-v1.0-os.html#type-binary) [AMQP value](https://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-messaging-v1.0-os.html#type-amqp-value).
+Token refresh is supported by RabbitMQ’s AMQP 1.0 clients in [Java](https://github.com/rabbitmq/rabbitmq-amqp-java-client), [.NET](https://github.com/rabbitmq/rabbitmq-amqp-dotnet-client), and [Erlang](https://github.com/rabbitmq/rabbitmq-server/tree/main/deps/rabbitmq_amqp_client).
+
+In the case of **AMQP 0.9.1**, when a token expires on an existing connection, the broker will refuse further operations after a limited time, but it will not disconnect the client.
+To refresh the token, the client should use the AMQP 0.9.1 [update-secret](/amqp-0-9-1-reference#connection.update-secret) method if supported by the client (for example, see the [Java client](/client-libraries/java-api-guide#oauth2-refreshing-token) documentation).
+If the client does not support `update-secret`, it must disconnect and reconnect with a new token.
 
 ### Scope-to-Permission translation {#scope-translation}