To make REST requests to a SmartApp, the client must establish a trusted relationship using an implementation of the OAuth2 Authorization Code Flow.


The general flow is:

  1. Request an authorization code.
  2. Use the code to request an access token.
  3. Get the endpoint URI for the SmartApp.
  4. Make REST calls to the SmartApp using the endpoint URI.

As part of the authorization flow, the SmartApp will be installed to the user’s selected Location.


Beginning February 1, 2016, only SmartApps approved and published by SmartThings can be installed via the OAuth flow discussed below.

For testing purposes, you will be able to install into your own account only.

For more information, see this community post.


Regardless of the server the SmartApp is actually published to, should be used to obtain the authorization code, access token, and endpoints.

Get authorization code

Authorization URL:

To obtain an authorization code, make a GET request to


The following parameters are required:

parameter value
response_type Use code to obtain the authorization code.
client_id The OAuth client ID of the SmartApp.
scope This should always be “app” for this authorization flow.
redirect_uri The URI of your server that will receive the authorization code. This URI must match one of the redirect URIs specified in the SmartApp settings, otherwise validation will fail.

This will require the user to log in with their SmartThings account credentials, choose a Location, and select what devices may be accessed by the third party.

The authorization code expires 24 hours after issue.

Get access token

Token URL:

Use the code you received to obtain the access token:

Content-Type: application/x-www-form-urlencoded


The content-type header of your request should be of the type application/x-www-form-urlencoded. The following form parameters are required:

parameter value
grant_type This is always “authorization_code” for this flow.
code The code you received.
client_id The client ID for the SmartApp.
client_secret The client secret for the SmartApp.
redirect_uri The URI of the server that will receive the token. This must match the URI you used to obtain the authorization code.

A successful response will look like this:

  "access_token": "XXXXXXXXXXXX",
  "expires_in": 1576799999,
  "token_type": "bearer"

The expires_in response is the time, in seconds from now, that this token will expire.

Once you have the token, it must be stored securely in the application.

Get SmartApp endpoints

You can use the token to request the callable endpoints of the SmartApp, by making a GET request to The access token should be supplied via a Authorization: Bearer header:

GET -H "Authorization: Bearer ACCESS-TOKEN" ""

A successful response will return a list of all installed SmartApps for the clientID associated with the given access token.

        "oauthClient": {
            "clientId": "CLIENT-ID"
        "location": {
            "id": ID,
            "name": "LOCATION-NAME"
        "uri": "BASE-URL/api/smartapps/installations/INSTALLATION-ID",
        "base_url": "BASE-URL",
        "url": "/api/smartapps/installations/INSTALLATION-ID"


The base_url (and base URL of the uri) will vary depending upon the server the SmartApp is being installed to.

SmartApps may be installed into any number of servers depending upon the location of the end-user. You should always use the uri and base_url to find the location this SmartApp can be reached at.

Do not assume that the SmartApp will be installed on

Make REST calls

Using the uri returned from /api/smartapps/endpoints, you can then make REST calls the SmartApp.

Simply append any paths your SmartApp declares in its mappings to make the appropriate request.

For example, assuming a mappings definition like this:

mappings {
    path("/switches") {
        action: [GET: "getSwitches"]

def getSwitches() {
    // ...

And a URI of, you can make a request to the /switches endpoint like this:

curl -H "Authorization: Bearer ACCESS-TOKEN" -X GET ""