Creates a token for temporary access.

Scenario

This operation is called by an application server to apply for a token from a Message Queue for MQTT broker after the application server verifies the permissions of the Message Queue for MQTT client. For more information, see Token authentication overview.

Limits

A single user can send a maximum of 100 requests per second. If you need to send more requests, submit a ticket.

Note Each successful call to the ApplyToken operation increases the number of messaging transactions per second (TPS) by one. Therefore, you are charged for the call. 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

Parameter Type Required Example Description
Action String Yes ApplyToken

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

RegionId String Yes cn-hangzhou

The region ID of the Message Queue for MQTT instance.

Resources String Yes TopicA/+

The name of the resource, that is, a specified topic on the Message Queue for MQTT instance. Separate multiple topics with commas (,). Each token can be used to run and manage up to 100 resources. Sort multiple topics in alphabetical order.

Resource parameters that you register to apply for a token can use MQTT wildcards, including the single-level wildcard represented by a plus sign (+) and the multi-level wildcard represented by a number sign (#).

For example, if you set Resources to Topic1/+ in the request to apply for a token, the Message Queue for MQTT client can manage topics of Topic1/xxx. If you set Resources to Topic1/# in the request to apply for a token, the Message Queue for MQTT client can manage multi-level topics of Topic1/xxx/xxx/xxx.

InstanceId String Yes post-cn-0pp12gl****

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

ExpireTime Long Yes 1609434121000

The timestamp that identifies when the token expires. Unit: milliseconds The minimum expiration interval is 60 seconds and the maximum expiration interval is 30 days. If you set this parameter to a value larger than 30 days, no errors are returned. However, the token takes effect only for 30 days.

Assume that you want to set the expiration interval of the token to 60 seconds. If the current system timestamp is 1609434061000, you must set the value of this parameter to 1609434121000, which is the sum of 1609434061000 and the product of 60 and 1000.

Actions String Yes R

The permission type of the token. Valid values:

  • R: Only read permissions are available, that is, you can subscribe to a specified topic but cannot produce messages to the topic.
  • W: Only write permissions are available, that is, you can produce messages to a specified topic but cannot subscribe to the topic.
  • R,W: Both read and write permissions are available, that is, you can produce messages to and subscribe to a specified topic. Separate R and W with a comma (,).
Note For more information about other parameters, see Common parameters and Endpoints.

Response parameters

Parameter Type Example Description
Token String LzMT+XLFl5s/YWJ/MlDz4t/Lq5HC1iGU1P28HAMaxYxn8aQbALNtml7QZKl9L9kPe6LqUb95tEVo+zUqOogs9+jZwDUSzsd4X4qaD3n2TrBEuMOqKkk1Xdrvu9VBQQvIYbz7MJWZDYC3DlW7gLEr33Cuj54iIhagtBi3epStJitsssWs7otY9zhKOSZxhr49G3d0bh35mwyP18EMvDas8UlzeSozsSrujNUqZXOGK0PEBSd+rWMGDJlCt6GFmJgm2JFY7PJwf/7OOSmUYIYFs5o/PuPpoTMF+hcVXMs+0yDukIMTOzG9m3t8k36PVrghFmnK6pC3Rt3mibjW****ng==

The token returned by the Message Queue for MQTT broker.

Note Do not assume the length, format, or rule of the token to return. The actual returned value prevails.
RequestId String 31782AAF-D0CC-44C3-ABFD-1B500276****

The ID of the request.

Examples

Sample request

http(s)://onsmqtt.cn-hangzhou.aliyuncs.com/?Action=ApplyToken
&Actions=R
&ExpireTime=1609434121000
&InstanceId=post-cn-0pp12gl****
&RegionId=cn-hangzhou
&Resources=TopicA/+
&<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

HttpCode Error code Error message Description
400 ApplyTokenOverFlow You 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.
400 CheckAccountInfoFailed An 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.
400 InstancePermissionCheckFailed An 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 Message Queue for MQTT instance.
400 ParameterCheckFailed An error occurred while validating the parameters. The parameters may be missing or invalid. The error message returned because parameter verification failed. Parameter values may be missing or invalid.
400 PermissionCheckFailed An 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.
400 InvalidParameter.%s An 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.
500 InternalError An error occurred while processing your request. Try again later. The error message returned because an internal error occurred to the Message Queue for MQTT instance. Try again.
500 SystemOverFlow An error occurred while processing your request. Please try again. The error message returned because throttling is triggered. Try again.
404 ApiNotSupport The specified API is not supported. The error message returned because the API operation is not supported.

For a list of error codes, visit the Error Center.