All Products
Search

This Product

    ApsaraMQ for MQTT:Token-based authentication

    Document Center

    ApsaraMQ for MQTT:Token-based authentication

    Last Updated:May 27, 2026

    ApsaraMQ for MQTT uses token-based authentication to grant temporary, fine-grained access control for a single client and a single resource. Your application server requests tokens from the MQTT broker and distributes them to clients managed by your on-premises account system.

    Terms

    Term

    Description

    Token (temporary credential)

    A temporary credential issued by ApsaraMQ for MQTT that grants a single client access to specific resources.

    Application server

    Your server that manages on-premises accounts and requests or manages tokens for MQTT clients.

    ApsaraMQ for MQTT broker

    The ApsaraMQ for MQTT server that authenticates permissions, processes token requests from application servers, and sends and receives messages.

    Authentication process

    Token-based authentication requires more setup than signature authentication. Deploy your application server as shown in the following figure, and ensure your MQTT client can interact with it to obtain and refresh tokens during initialization.

    Figure 1. Authentication processtoken_process_new

    The authentication process works as follows:

    1. The MQTT client starts and connects to the application server for authentication.

    2. The client requests permissions for a specific topic from the application server.

    3. The application server verifies client permissions for the topic. If verification passes, it requests a token from the ApsaraMQ for MQTT broker.

    4. The ApsaraMQ for MQTT broker validates the request and returns the token.

    5. The application server caches the token and maps it to the granted permissions. Caching provides the following benefits:

      • If the client reconnects with the same permissions, the server returns the cached token instead of requesting a new one.

      • If the broker is temporarily unavailable, the server returns the cached token for local disaster recovery.

    6. The client passes the token in its connection parameters and connects to the broker. After authentication succeeds, the client can send and receive messages.

    7. The client sends and receives messages. When the broker detects an expired token, it disconnects the client. The client must then re-apply for a token.

    Client requirements

    • Obtain the token and its expiration time from the application server to calculate when to refresh the token.

    • Pass the token in the Password field each time a connection is established.

    • Track the token validity period. If the token expires, the broker disconnects the client.

    • The client can listen to token expiration notifications from the broker. However, delivery is not guaranteed — use these notifications only for troubleshooting.

    • Persistently store the token to avoid requesting the same token on each reconnection. If many clients reconnect simultaneously without cached tokens, the application server unexpectedly quits.

    • To update a token, either reconnect with a new token or use the system-defined topic to dynamically update it. If you use dynamic updates, also update the on-premises configuration for subsequent connection initializations.

    Application server requirements

    • Authenticate each MQTT client to prevent token requests with forged identities.

    • Track token-client mappings, granted permissions, and validity periods to prevent duplicate token requests from the same client.

    • Return the token along with its permissions and expiration time so the client can refresh the token before it expires.

    • Implement local disaster recovery to ensure business continuity when the broker is temporarily unavailable.

    API operations

    Token-based authentication is implemented through the following API operations:

    • Application servers interact with the ApsaraMQ for MQTT broker over HTTPS for token application and revocation.

      Each API operation requires identity verification with an AccessKey pair and request signature. Token application, revocation, and verification operations are described in Application server-related methods in token authentication.

    • ApsaraMQ for MQTT clients support dynamic token updates, token expiration notifications, and token invalidity notifications. These operations are described in Client-related methods in token authentication.