Authorization Management

Last Updated on : 2024-10-23 06:44:31download

This topic describes the APIs related to authorization management.

API list

Request method	API	Description
GET	/v1.0/token	Get the access token.
GET	/v1.0/token/{refresh_token}	Refresh the user token.
POST	/v1.0/users/{uid}/ticket	Generate a login-free token.

Get a token

API description

Get a token by using the authorized credential generated from a cloud application created on Tuya Developer Platform. You can get a token in simple mode or authorization mode. For differences between the two modes, see Authorization Mode.

API address

GET /v1.0/token

Request parameters

Parameter	Type	Parameter type	Required	Description
grant_type	Integer	URL	Yes	The authorization type. `1`: simple mode `3`: authorization mode
code	String	URL	No	The authorization code, which is required if `grant_type` is set to 3. For more information, see Authorization Mode.
associate_id	String	URL	No	The association ID, which is required if `grant_type` is set to 3. For more information, see Authorization Mode.

Response parameters

Parameter	Type	Description
code	Integer	The response code. For more information, see Error code.
success	Boolean	Indicates whether the request succeeds. `true`: succeeded `false`: failed
msg	String	The message returned if the request fails. If the request succeeds, null is returned.
result	Object<result>	The token information.

Result details

Parameter	Type	Description
uid	String	The ID of the Tuya user.
access_token	String	The access token.
refresh_token	String	The refresh token.
expire	Integer	The valid period, in seconds.

Sample request

GET /v1.0/token?grant_type=1

Sample response

{
  "success":true,
  "result": {
      "uid":" euxxxxxxxxx",
      "access_token": "",
      "expire_time": 7200,
      "refresh_token": ""
  }
}

Error code

The following error codes indicate common service exceptions returned by this API. For more error codes, see Global Error Codes.

Error code	Description
500	The system error.
1003	The invalid grant type.
1107	The invalid code.

Refresh the token

API description

The OAuth token is currently valid only for two hours for security concerns. After it expires, you must call refresh_token to get a new token.

The access_token has a limited validity period but no restrictions on the number of times it can be used during that period.
The refresh_token does not have a validity period limit but can only be used once.

API address

GET /v1.0/token/{refresh_token}

Sample request

GET /v1.0/token/xxxxxx

Sample response

{
  "success":true,
  "result": {
      "uid":" euxxxxxxxxx",
      "access_token": "",
      "expire_time": 7200,
      "refresh_token": ""
  }
}

Error code

The following error codes indicate common service exceptions returned by this API. For more error codes, see Global Error Codes.

Error code	Description
500	The system error.
1003	The invalid grant type.
1107	The invalid code.

Generate a login-free token

API description

Generate a login-free token based on the Tuya user ID (UID). The token is used in specific scenarios or required by certain APIs.

API address

POST /v1.0/users/{uid}/ticket

Request parameters

Parameter	Type	Parameter type	Required	Description
uid	String	URI	Yes	The ID of the Tuya user.

Sample request

POST /v1.0/users/ay1541161424063AjySj/ticket

Response parameters

Parameter	Type	Description
code	Integer	The response code. For more information, see Error code.
success	Boolean	Indicates whether the request succeeds. `true`: succeeded `false`: failed
msg	String	The message returned if the request fails. If the request succeeds, null is returned.
result	Object	The token information.

Sample response

{
    "success":true,
    "result": {
        "ticket":" e0dcadc407806d0360a4df9f5b9f7942",
        "expire_time":300
    }
}

Error code

Error code	Description
500	The system error.

Prev DocIntegration Guide

Next DocAuthorization Mode