Authorization and Permissions

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

There are two types of tokens:

  • SmartApp tokens, and
  • 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. 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.
l:installedapps View a list of installed SmartApps. 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:installedapps:* Create, update, or delete installed SmartApps. 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.
r:apps:* Read details about a SmartApp. Only applicable for personal access tokens, and the scope is limited to the SmartApps associated with the token’s account.
w:apps:* Create, update, or delete SmartApps. 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.
l:devices View a list of devices. 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.
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.
r:deviceprofiles View details of device profiles associated with the account. Only applicable for personal access tokens.
w:deviceprofiles Create, update, or delete device profiles. Only applicable to personal access tokens, and the device profile must be owned by the same account associated with the token.
i:deviceprofiles Create devices of the type associated with the device profile. Only applicable for SmartApp tokens, and is requires the device profile and the SmartApp have the same account owner.
r:schedules Read details of scheduled executions. 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.
w:schedules Create, update, or delete schedules. 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.
l:locations View a list of locations. Only applicable for personal access tokens, and the scope is limited to the account associated with the token.
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.
w:locations:* Create, update, and delete locations. Only applicable for personal access tokens.
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.

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.

    NOTE

    The SmartThings Developer Workspace will require you to select a set of OAuth scopes to be whitelisted for your SmartApp.

  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

NOTE

Whether you are using Developer Workspace or working on command line, you are required to explicitly select a set of OAuth scopes to be whitelisted for your SmartApp.


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 updating a SmartApp’s OAuth settings to allow the SmartApp 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:*",
    "r:schedules",
    "w:schedules"
  ],
  "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 request header.

NOTE

The authToken expiration is five minutes; your SmartApp is expected to make calls to the SmartThings API within this duration after receiving the request from SmartThings.


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.

Store your refresh token!

Be sure to securely store the refresh token so your SmartApp can use it later.


Refreshing your tokens

To obtain a new token set, consisting of a new access token and a new refresh token, 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'

Store your refresh token!

The Client ID and Client Secret can be found in Developer Workspace when creating your SmartApp. They will be only be displayed once, so be sure to note them when creating your SmartApp.


SmartApp token duration

SmartApp authorization and refresh token expiration durations are:

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

Preventing refresh token expiry

If your refresh token expires after 30 days, currently we have no easy option. 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
List all devices l:devices View a list of devices that the account associated with the token has access to.
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.
List all installed apps l:installedapps View a list of installed SmartApps. 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.
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.
Write all locations w:locations:* Create, update, and delete locations for the account associated with this token.
Read all apps r:apps:* Read details about SmartApps associated with the token’s account.
Write all apps w:apps* Create, update, or delete SmartApps associated with the token’s account.
Read all device profiles r:deviceprofiles View details of device profiles associated with the account.
Write all device profiles w:deviceprofiles Create, update, or delete device profiles. The device profile must be owned by the same account associated with the token.
Read all schedules r:schedules Read details of scheduled executions associated with the token’s account.
Write all schedules w:schedules Create, update, or delete schedules associated with the token’s account.

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 are required 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"
  }

Requesting permissions to create and read schedules

SmartApps may create schedules to trigger executions of your SmartApp at a defined time or recurring schedule. To do so, your SmartApp needs the w:schedules permission, which should be requested during the INITIALIZE lifecycle phase.

The example below shows a sample response to the INITIALIZE lifecycle phase, to request permission to read and write (create, update, and delete) schedules:

{
  "name": "My Scheduling SmartApp",
  "description": "Scheduling SmartApp",
  "id": "app",
  "permissions":["r:schedules", "w:schedules"],
  "firstPageId": "1"
  }

Best practices

  • Your SmartApp should never request permissions it does not need. For example, if your app never creates schedules, do not request the "w:schedules" permission.
  • 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.