Creates a token for temporary access.

Scenarios

This operation is called by an application server to apply for a token from a ApsaraMQ for MQTT broker after the application server verifies the permissions of the ApsaraMQ for MQTT client. For more information, see Overview of token-based authentication.

Limits

A user can send up to 100 requests per second. If you want to increase the limit on the number of requests that a user can send per second, join the DingTalk group 35228338 to contact ApsaraMQ for MQTT technical support.

Note Each successful call to the ApplyToken operation increases the number of messaging transactions per second (TPS) by one. This affects your billing. For more information, see Billing.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

ParameterTypeRequiredExampleDescription
ActionStringYesApplyToken

The operation that you want to perform. Set the value to ApplyToken.

ResourcesStringYesTopicA/+

The name of the topics in the ApsaraMQ for MQTT instance. Separate topic names with commas (,). Each token can be used to manage up to 100 topic names. Topic names are sorted in alphabetical order.

MQTT wildcards, including single-level wildcards represented by plus signs (+) and multi-level wildcards represented by number signs (#), can be used for the Resources parameter that you register to apply for a token.

For example, if you set the Resources parameter to Topic1/+ when you apply for a token, the ApsaraMQ for MQTT client can manage the topics of Topic1/xxx. If you set the Resources parameter to Topic1/# when you apply for a token, the ApsaraMQ for MQTT client can manage any level of topics in Topic1/xxx/xxx/xxx.

Note ApsaraMQ for MQTT supports subtopics. You can specify subtopics in the code for messaging instead of configuring them in the ApsaraMQ for MQTT console. Forward slashes (/) are used to separate topics of different levels. For more information, see Terms.
InstanceIdStringYespost-cn-0pp12gl****

The ID of the ApsaraMQ for MQTT instance. The value must be the same as the instance ID that is used by the ApsaraMQ for MQTT client. You can obtain the instance ID on the Instance Details page in the ApsaraMQ for MQTT console.

ExpireTimeLongYes1609434121000

The timestamp that indicates the point in time when the token expires. Unit: milliseconds. The minimum validity period of a token is 60 seconds, and the maximum validity period of a token is 30 days. If you set a validity period to more than 30 days, no errors are returned. However, the token is valid only for 30 days.

Assume that you want to set the validity period of a token to 60 seconds. If the current system timestamp is 1609434061000, you must set the value of this parameter to 1609434121000 based on the following formula: 1609434061000 + 60 x 1000 = 1609434121000.

ActionsStringYesR

The permission type of the token. Valid values:

  • R: read-only. You can subscribe to specific topics but not send messages to the topics.
  • W: write-only. You can send messages to specified topics but not subscribe to the topics.
  • R,W: read and write. You can send messages to and subscribe to specified topics. Separate R and W with a comma (,).
Note For more information about parameters, see Common parameters and Endpoints.

Response parameters

ParameterTypeExampleDescription
TokenStringLzMT+XLFl5s/YWJ/MlDz4t/Lq5HC1iGU1P28HAMaxYxn8aQbALNtml7QZKl9L9kPe6LqUb95tEVo+zUqOogs9+jZwDUSzsd4X4qaD3n2TrBEuMOqKkk1Xdrvu9VBQQvIYbz7MJWZDYC3DlW7gLEr33Cuj54iIhagtBi3epStJitsssWs7otY9zhKOSZxhr49G3d0bh35mwyP18EMvDas8UlzeSozsSrujNUqZXOGK0PEBSd+rWMGDJlCt6GFmJgm2JFY7PJwf/7OOSmUYIYFs5o/PuPpoTMF+hcVXMs+0yDukIMTOzG9m3t8k36PVrghFmnK6pC3Rt3mibjW****ng==

The token value returned by the ApsaraMQ for MQTT broker.

Note Do not assume the length, format, or rule of the token that is returned. The actual returned value prevails.
RequestIdString31782AAF-D0CC-44C3-ABFD-1B500276****

The ID of the request. This parameter is a common parameter. Each request has a unique ID.

Examples

Sample requests

http(s)://onsmqtt.cn-hangzhou.aliyuncs.com/?Action=ApplyToken
&Resources=TopicA/+
&InstanceId=post-cn-0pp12gl****
&ExpireTime=1609434121000
&Actions=R
&Common request parameters

Sample success responses

XML format

HTTP/1.1 200 OK
Content-Type:application/xml

<ApplyTokenResponse>
    <RequestId>31782AAF-D0CC-44C3-ABFD-1B500276****</RequestId>
    <Token>LzMT+XLFl5s/YWJ/MlDz4t/Lq5HC1iGU1P28HAMaxYxn8aQbALNtml7QZKl9L9kPe6LqUb95tEVo+zUqOogs9+jZwDUSzsd4X4qaD3n2TrBEuMOqKkk1Xdrvu9VBQQvIYbz7MJWZDYC3DlW7gLEr33Cuj54iIhagtBi3epStJitsssWs7otY9zhKOSZxhr49G3d0bh35mwyP18EMvDas8UlzeSozsSrujNUqZXOGK0PEBSd+rWMGDJlCt6GFmJgm2JFY7PJwf/7OOSmUYIYFs5o/PuPpoTMF+hcVXMs+0yDukIMTOzG9m3t8k36PVrghFmnK6pC3Rt3mibjW****ng==</Token>
</ApplyTokenResponse>

JSON format

HTTP/1.1 200 OK
Content-Type:application/json

{
  "RequestId" : "31782AAF-D0CC-44C3-ABFD-1B500276****",
  "Token" : "LzMT+XLFl5s/YWJ/MlDz4t/Lq5HC1iGU1P28HAMaxYxn8aQbALNtml7QZKl9L9kPe6LqUb95tEVo+zUqOogs9+jZwDUSzsd4X4qaD3n2TrBEuMOqKkk1Xdrvu9VBQQvIYbz7MJWZDYC3DlW7gLEr33Cuj54iIhagtBi3epStJitsssWs7otY9zhKOSZxhr49G3d0bh35mwyP18EMvDas8UlzeSozsSrujNUqZXOGK0PEBSd+rWMGDJlCt6GFmJgm2JFY7PJwf/7OOSmUYIYFs5o/PuPpoTMF+hcVXMs+0yDukIMTOzG9m3t8k36PVrghFmnK6pC3Rt3mibjW****ng=="
}

Error codes

HttpCodeError codeError messageDescription
400ApplyTokenOverFlowYou have applied for tokens too many times. Please try again later.The error message returned because token application is too frequent and throttling is triggered by the system. Try again later.
400CheckAccountInfoFailedAn error occurred while checking the account information by the STS token.The error message returned because the account information of the Security Token Service (STS) token failed to be parsed.
400InstancePermissionCheckFailedAn error occurred while validating the permissions of the instance. Please verify the account that created the instance and its permissions settings.The error message returned because instance permission verification failed. Check the ownership and authorization policy of the ApsaraMQ for MQTT instance.
400ParameterCheckFailedAn error occurred while validating the parameters. The parameters may be missing or invalid. The error message returned because the parameter failed to be verified. The parameter may be missing or invalid.
400PermissionCheckFailedAn error occurred while validating the resource permissions. Please check the account that created the instance, topic, and GroupId, and check their permission settings. The error message returned because resource permission verification failed. Check the permissions and authorization policies of the instance, topic, and group ID.
400InvalidParameter.%sAn error occurred while validating the parameter. The parameter may be missing or invalid.The error message returned because the parameter failed to be verified. The parameter may be missing or invalid.
500InternalErrorAn error occurred while processing your request. Try again later.The error message returned because a backend service error occurred to the ApsaraMQ for MQTT instance. Try again.
500SystemOverFlowAn error occurred while processing your request. Please try again.The error message returned because throttling is triggered. Try again.
404ApiNotSupportThe specified API is not supported.The error message returned because the API operation is not supported.

For a list of error codes, see Service error codes.