How to retrieve an access token? Documentation is incomplete with dead links. :(

Developer Programs Support
1

I have already worked with countless APIs, but none have given me as many headaches as the SmartThings API! :roll_eyes:

The documentation is incomplete, links are dead, URLs no longer work, have been changed, but no indication of the new URL, and due to all such changes, the solutions found here in the community are no longer functional either. :confounded:

At least I have already found out that /subscriptions from InstalledApps do not work with the PAT, but require their own access token.
However, I canā€™t find any information about this.
The relevant links in the documentation (ā€œFor more information about authorization and permissions, visit the Authorization section in the SmartThings documentation.ā€) no longer work, nor does the URL (https://auth-global.api.smartthings.com/).

I therefore ask for help on how to retrieve the access token for an InstalledApp.

2

I only currently have experience for InstalledApp instances for Webhook SmartApps. With those a temporary access token valid for five minutes is delivered in the body of each EVENT lifecycle request.

Subscriptions are typically set up in the INSTALL or UPDATE lifecycle. An access token valid for 24 hours and a refresh token valid for 30 days are delivered in the body of those lifecycle requests. If you might need an access token at another time and the temporary tokens donā€™t help, your app should save these longer lasting tokens somewhere and handle refreshing of them as required.

3

Hi, @Bluebrain
It would be useful for us if you could share with us which links in the developer portal youā€™ve found that no longer work, please. I saw one link referring to ā€œAuthorization and permissionsā€ and it works correctly sending us to https://developer.smartthings.com/docs/getting-started/authorization-and-permissions.

What @orangebucket mentioned above is correct, the URL of https://auth-global.api.smartthings.com/ used to be for SmartApps in Groovy, right? In that case, SmartApps where a different concept.
Currently, you get the access token in the ā€œcontextā€ of the SmartApp, you cannot call an API endpoint to get that information. For example, this is the request you get when you authorize the installation in the ST app:

INSTALL REQUEST: {
  "lifecycle": "INSTALL",
  "executionId": "2f75803e-0cfe-9261-...",
  "appId": "85b3ceb2-4de6-4c05-...",
  "locale": "en",
  "version": "0.1.0",
  "client": {
    "os": "android",
    "version": "1.8.14.26",
    "language": "en-US",
    "displayMode": "LIGHT",
    "timeZoneOffset": "",
    "supportedTemplates": [],
    "samsungAccountId": "",
    "mobileDeviceId": ""
  },
  "installData": {
    "authToken": "5434de0c-0232-461c-...",
    "refreshToken": "1f58474f-3545-462c-...",
    "installedApp": {
      "installedAppId": "1f13ed33-6f43-4fd0-...",
      "locationId": "0b018721-6bc0-483c-...",
      "config": {
        "sensor": [
          {
            "valueType": "DEVICE",
            "deviceConfig": {
              "deviceId": "5e9aacc2-68f8-4ae4-...",
              "componentId": "main"
            }
          }
        ],
        "lights": [
          {
            "valueType": "DEVICE",
            "deviceConfig": {
              "deviceId": "08341238-0815-458e-...",
              "componentId": "main"
            }
          }
        ]
      },
      "permissions": [...]
    }
  },
  "settings": {}
}

Something important to note is that Webhook SmartApps are for self-publish only. This means only for personal use.

Thereā€™s another example about OAuth integration (here) where you have a server that asks for userā€™s authorization that returns a token with an installedAppId as shown here:

{
   "access_token":"41fb5735-d9af-4041-...",
   "token_type":"bearer",
   "refresh_token":"f804c515-2afa-4a49-...",
   "expires_in":85744,
   "scope":"r:locations:* x:devices:* r:devices:*",
   "access_tier":0,
   "installed_app_id":"cac8fb70-4e2c-4630-..."
}

This is not installed/authorized from the SmartThings app like a Webhook/Lambda SmartApp.

4

The dead link and wrong endpoint are right at the beginning of the dev documentation:
API | Developer Documentation | SmartThings.

2024-06-11_02-42-39
2024-06-11_02-42-391184Ɨ549 93.5 KB

I now try to figure out token lifetime, refreshing a token, etc. but cannot find the documentation about it.

1 Like
5

Thanks for the info @Bluebrain, I created a ticket about that

About this URL, it seems I was wrong and itā€™s still live, Iā€™ll check more details about it.

About the token lifetime, refreshing process, it depends on where you get it from. Which type of integration did you choose?

6

I installed it in the ST app and got the tokens via the INSTALL lifecycle webhook notification.

7

OK, the tokens we get from the INSTALL and UPDATE lifecycles expire in 24 hours.
About refreshing your token, you can call: https://api.smartthings.com/oauth/token, this is an example for that request:

curl --location 'https://api.smartthings.com/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic <authorizationInfo>' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'refresh_token=xxxx-xxxx-....'

You need to replace <authorizationInfo> for the encoded values of clientId:clientSecret of the SmartApp. For example, this is how I encoded it in NodeJS:

let encodedclientid_secret = encoder64.encode(
	`${client_id}:${client_secret}`,
	'base64')
1 Like
8

Great! Thanks for your help.
How long is the, then renewed, token valid? Also 24 hours?
And how long is the refresh token valid? I think I read somewhere 30 days.

Is there no documentation available for all of this?

9

yes, when you refresh it through that endpoint, you receive the value of expires_in in seconds and converting it it is in 24 hours.

Yes, I also asked the team and they mentioned that if you donā€™t use it to get a new Access Token, it remains valid for those 30 days. Otherwise, by getting a new Access Token, the previous refresh token becomes invalid (also tested that myself).

We were also checking this internally since I shared your case and comments but it seems thereā€™s no specific documentation, so, while you work on this, we can solve your doubts here.

2 Likes