Authorization and Permissions

All SmartThings resources are protected with OAuth 2.0 Bearer Tokens sent on the request as an Authorization: Bearer <TOKEN> header, and operations require specific OAuth scopes that specify the exact permissions authorized by the user.

There are two types of tokens:

  • SmartApp tokens
  • Personal access tokens.

Personal access tokens

Personal access tokens are used to interact with the API for non-SmartApp use cases. They can be created and managed on the personal access tokens page.

When creating personal access tokens, you select the specific permissions that should be granted to the token. These permissions define the OAuth2 scopes for the personal access token.

SmartApp tokens

SmartApp tokens are used to communicate between third-party integrations, or SmartApps, and the SmartThings API.

When a SmartApp is called by the SmartThings platform, it is sent an authorization token that can be used by the SmartApp to interact with the SmartThings API.

See Using SmartApp tokens for more information about using SmartApp authorization tokens.


OAuth2 scopes

Permissions that you select will define the OAuth scopes for the token. Operations are protected by these specific OAuth scopes. In specific:

  • Personal access token scopes are associated with the specific permissions selected when creating them.

  • SmartApp token scopes are derived from the permissions requested by the SmartApp and granted by the end-user during installation.

Scopes are generally in the form permission:entity-type:entity-id.

An * used for the entity-id specifies that the permission may be applied to all entities that the token type has access to, or may be replaced with a specific ID.

Scope Description
r:installedapps:*

Read details about installed SmartApps, such as which devices have been configured for the installation. Only applicable for personal access tokens, and the scope is limited to the account associated with the token.
w:installedapps:*

Create, update, or delete installed SmartApps. Only applicable for personal access tokens, and the scope is limited to the account associated with the token.
r:devices:*

Read details about a device, including device attribute state. For SmartApp tokens, the scope is restricted to the location the SmartApp is installed into. For personal access tokens, the scope is limited to the account associated with the token. This scope is required to create subscriptions.
w:devices:*

Update details such as the device name, or delete a device. For SmartApp tokens, the scope is restricted to the location the SmartApp is installed into. For personal access tokens, the scope is limited to the account associated with the token.
x:devices:*

Execute commands on a device. For SmartApp tokens, the scope is restricted to the location the SmartApp is installed into. For personal access tokens, the scope is limited to the account associated with the token.
i:deviceprofiles

Create devices of the type associated with the device profile. Only applicable for SmartApp tokens, and requires that the device profile and the SmartApp have the same account owner.
r:locations:*

Read details of a location, such as geo-coordinates and temperature scale. For SmartApp tokens, the scope is restricted to the installed SmartApp. For personal access tokens, the scope is limited to the account associated with the token.
x:locations:*

Execute commands at a Location. For SmartApp tokens, the scope is restricted to the installed SmartApp. For personal access tokens, the scope is limited to the account associated with the token.
r:scenes:*

Get all the scenes. Only for personal access tokens, and the scope is limited to the account associated with the token.
x:scenes:*

Execute scenes. Only for personal access tokens, and the scope is limited to the account associated with the token.
r:rules:*

Get all the rules. For SmartApp tokens, the scope is restricted to the location the SmartApp is installed into. For personal access tokens, the scope is limited to the account associated with the token.
w:rules:*

Create or Update a rule. For SmartApp tokens, the scope is restricted to the location the SmartApp is installed into. For personal access tokens, the scope is limited to the account associated with the token.
x:rules:*

Execute the rule. For SmartApp tokens, the scope is restricted to the location the SmartApp is installed into. For personal access tokens, the scope is limited to the account associated with the token.

Using SmartApp tokens

When SmartThings sends a request to your SmartApp for the INSTALL, UPDATE, and EVENT lifecycles, it includes an authorization token on the request body. The authorization token has its OAuth scopes defined as below.

OAuth scopes for SmartApp token

The scopes for a SmartApp token are derived from the following steps:

  1. When you create a SmartApp, you must also ensure that a set of OAuth scopes are whitelisted for your SmartApp. These whitelisted scopes are what your SmartApp may request during the installation process.

  2. In your SmartApp, during the INITIALIZE phase of the CONFIGURATION lifecycle, you specify any non-entity-specific permissions your SmartApp requires. Entity-specific permissions, such as device-specific permissions, are handled by the DEVICE setting. The permissions requested must be present in the whitelist defined in step 1).

  3. The specific OAuth scopes for an installation are then created from the requested permissions in 1) and 2) above.

Whitelisting OAuth scopes


Setting and updating the whitelisted OAuth scopes

To explicitly whitelist the OAuth scopes or to update the OAuth scopes, which may be requested by your SmartApp, make a request to the /apps/YOUR-APP-ID/oauth API (API docs), using a personal access token (the token must have the w:apps:* permission).

The example below shows a request to update a SmartApp's OAuth settings. In this example the SmartApp will be able to request permissions to read and execute commands on devices, as well as read and write schedules. You should replace the scope values with those required for your SmartApp.

curl -X "PUT" "https://api.smartthings.com/apps/YOUR-APP-ID/oauth" \
     -H "Authorization: Bearer YOUR-PERSONAL-ACCESS-TOKEN" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d $'{
  "scope": [
    "r:devices:*",
    "x:devices:*"
  ],
  "clientName": "Your OAuth client name"
}'

Using the authorization token

An authorization token is sent to your SmartApp during the INSTALL, UPDATE, EVENT, and UNINSTALL lifecycle phases:

{
  "lifecycle": "INSTALL",
  "executionId": "b328f242-c602-4204-8d73-33c48ae180af",
  "locale": "en",
  "version": "1.0.0",
  "installData": {
    "authToken": "bc9cd752-d00f-4125-9b69-edb7257b533a",
    "refreshToken": "97528e71-d550-43e7-943c-72d62e0a4c19",
    "installedApp": {...}
  }
}

You can then use the authToken to make requests to the SmartThings API by sending it as an Authorization: Bearer <token> request header.


Using the refresh token

A refresh token is sent to your SmartApp during the INSTALL and UPDATE lifecycle phases:

{
  "lifecycle": "UPDATE",
  "executionId": "d328f242-c602-4204-8d73-33c48ae180af",
  "locale": "en",
  "version": "1.0.0",
  "updateData": {
    "authToken": "bc9cd752-d00f-4125-9b69-edb7257b533a",
    "refreshToken": "97528e71-d550-43e7-943c-72d62e0a4c19",
    "installedApp": {...}
  }
}

If your SmartApp makes requests outside of being called by SmartThings, you will need to use the refresh token, along with the OAuth Client ID and secret associated with your SmartApp, to receive a new pair of access token and refresh tokens.


Refreshing your tokens

To obtain a new token set (access and refresh), make a POST request to https://auth-global.api.smartthings.com/oauth/token, using the latest unexpired refresh token, client ID, and client secret.

The request requires user authentication; the client ID is used as the user, and the client secret as the password.

The following form data should be sent on the request:

Parameter Description
grant_type

Specify refresh_token to receive a new token.

client_id

The client ID of your SmartApp.
client_secret

The client secret of your SmartApp.
refresh_token

The latest unexpired refresh token received by your SmartApp during the INSTALL or UPDATE phase.

An example request using cURL:

curl -X POST "https://auth-global.api.smartthings.com/oauth/token" \
     -u "YOUR-CLIENT-ID":"YOUR-CLIENT-SECRET" \
     -d 'grant_type=refresh_token&client_id=YOUR-CLIENT-ID&client_secret=YOUR-CLIENT-SECRET&refresh_token=YOUR-REFRESH-TOKEN'

SmartApp token duration

SmartApp authorization and refresh token expiration durations are:

  • Authorization tokens: five minutes
  • Refresh tokens: thirty days

Preventing refresh token expiry

Refresh tokens expire after 30 days, and we currently do not have an easy option to get a new one once it expires. Be sure to set up some schedule to refresh your tokens every two weeks to avoid this situation.

For example, use Creating scheduled executions to create a cron schedule to execute every 15 days to ensure that the refresh token will never expire.


Using personal access tokens

When creating a personal access token on the personal access token page, you select the specific permissions granted for that token. The permissions map to the specific OAuth scopes as documented in the table below:

Permission OAuth scope Description
Read all devices r:devices:*

Read details about a device, including device attribute state. The scope is limited to the account associated with the token. This scope is required to create subscriptions.
Write all devices w:devices:*

Update details such as the device name, or delete a device. The scope is limited to the account associated with the token.
Execute all devices x:devices:*

Execute commands on a device. The scope is limited to the account associated with the token.
Read all installed apps r:installedapps:*

Read details about installed SmartApps, such as which devices have been configured for the installation. The scope is limited to the account associated with the token.
Write all installed apps w:installedapps:*

Create, update, or delete installed SmartApps. The scope is limited to the account associated with the token.
Read all locations r:locations:*

Read details of a location, such as geocoordinates and temperature scale. The scope is limited to the account associated with the token.
Execute all locations x:locations:*

Execute commands at a Location. The scope is limited to the account associated with the token.
Create device types i:deviceprofiles

Create devices of the type associated with the device profile. Only applicable for SmartApp tokens, and requires that the device profile and the SmartApp have the same account owner.
Read all scenes r:scenes:*

Get all the scenes. Only for personal access tokens, and the scope is limited to the account associated with the token.
Execute all scenes x:scenes:*

Execute scenes. Only for personal access tokens, and the scope is limited to the account associated with the token.

Personal access token duration

Personal access tokens have an expiration duration of fifty years from the time of token creation.


SmartApp examples

The examples below show how permissions are requested in some common scenarios.

Requesting permissions for specific devices

A common scenario is to request the user select specific devices to work with the SmartApp. This happens during the CONFIGURATION lifecycle phase, using the DEVICE setting. Each DEVICE setting configuration specifies the specific permissions requested for that device:

Permission Description
r

Read details about the device. Required for creating subscriptions.

x

Execute commands on the device.
w

Update data about the device itself.

The example below shows a DEVICE setting to request that the user select a device that supports the Color Control capability, and requests the ability to read the device (including creating subscriptions for the device), and execute commands on the device:

{
  "name": "Set the color of this light",
  "settings": [
    {
      "id": "colorLight",
      "name": "Which color light?",
      "description": "Tap to set",
      "type": "DEVICE",
      "required": true,
      "multiple": false,
      "capabilities": ["colorControl"],
      "permissions": ["r", "x"]
    }
  ]
}

No additional permissions need to be requested during the INITIALIZE lifecycle phase response.


Requesting permissions for all devices

If you SmartApp would like access to all devices in the user's location, you will need to request the r:devices:* permission in the SmartApp's INITIALIZE lifecycle phase response.

Below is an example response to the INITIALIZE lifecycle phase that requests the read and execute permissions for all devices in the user's location:

{
  "name": "My SmartApp",
  "description": "Device control SmartApp",
  "id": "app",
  "permissions":["r:devices:*", "w:devices:*"],
  "firstPageId": "1"
  }

Best practices

  • Your SmartApp should never request permissions it does not need.
  • Remember that permissions are independent - "write" permission does not also imply "read" permission. Your app needs to request all specific permissions it may need.
  • Be sure to set up some schedule to refresh your tokens every 15 days to avoid refresh token expiration. If your refresh token expires after 30 days, currently we have no easy option.