Authorization Management

This topic describes the APIs related to authorization management.

API list

Request method	API name	Description
GET	/v1.0/token	Get an access token.
GET	/v1.0/authorize_token	Get an access token in authorization mode.
GET	/v1.0/token/{refresh_token}	Refresh the user token.
POST	/v1.0/users/{uid}/ticket	Get a login-free token.

Get an access token

API description

Create an authorization key corresponding to the cloud application on the Tuya Developer Platform and get a token.

API endpoint

GET /v1.0/token

Request parameters

Parameter	Type	Parameter type	Required	Description
grant_type	Integer	URL	Yes	The authorization type. 1: simple mode.

Response parameters

Parameter	Type	Description
code	Integer	The response code. For more information, see Error codes.
success	Boolean	Indicates whether the API call is successful. Valid values: true: success. false: failure.
msg	String	The error message returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object< result >	The token information.

Description of result

Parameter	Type	Description
uid	String	The user ID assigned by Tuya.
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":"eu*****",
      "access_token": "",
      "expire_time": 7200,
      "refresh_token": ""
  }
}

Error codes

The following table lists common error codes returned in the API calls. For more error codes, see Global Error Codes.

Error code	Description
500	A system error has occurred while processing your request.
1003	Invalid grant_type.
1107	Invalid code.

Get an access token in authorization mode

API description

Create an authorization key corresponding to the cloud application on the Tuya Developer Platform and get a token in authorization mode. For the differences between simple mode and authorization mode, refer to Authorization Mode.

API endpoint

GET /v1.0/authorize_token

Request parameters

Parameter	Type	Parameter type	Required	Description
grant_type	Integer	URL	Yes	The authorization type. 3: the authorization mode.
code	String	URL	No	The authorization code. For more information, see Authorization Mode.
associate_id	String	URL	No	The authorization relationship. For more information, see Authorization Mode.

Response parameters

Parameter	Type	Description
code	Integer	The response code. For more information, see Error codes.
success	Boolean	Indicates whether the API call is successful. Valid values: true: success. false: failure.
msg	String	The error message returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object< result >	The token information.

Description of result

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

Sample request

GET /v1.0/authorize_token?grant_type=3&code=39f3e****8e50&associate_id=179540****7411

Sample response

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

Error codes

The following table lists common error codes returned in the API calls. For more error codes, see Global Error Codes.

Error code	Description
500	A system error has occurred while processing your request.
1003	Invalid grant_type.
1107	Invalid code.

Get a refresh token

API description

The OAuth token is currently valid for two hours for security concerns. After it has expired, you need to call refresh_token to get a new token.

API endpoint

GET /v1.0/token/{refresh_token}

Sample request

GET /v1.0/token/xxxxxx

Sample response

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

Error codes

The following table lists common error codes returned in the API calls. For more error codes, see Global Error Codes.

Error code	Description
500	A system error has occurred while processing your request.
1003	Invalid grant_type.
1107	Invalid code.

Get a login-free token

API description

Generate a login-free token according to the Tuya user ID (UID). The token is used in certain scenarios or by some APIs.

API endpoint

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

Request parameters

Parameter	Type	Parameter type	Required	Description
uid	String	URI	Yes	The user ID assigned by Tuya.

Sample request

POST /v1.0/users/ay1541161424063Aj***/ticket

Response parameters

Parameter	Type	Description
code	Integer	The response code. For more information, see Error codes.
success	Boolean	Indicates whether the API call is successful. Valid values: true: success. false: failure.
msg	String	The error message returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	The token information.

Sample response

{
    "success":true,
    "result":{
        "ticket":"e0dcadc407806d0360a4df9f5b9f7***",
        "expire_time":300
    }
}

Error codes

Error code	Description
500	A system error has occurred while processing your request.