OK, let’s see what I can do using a Windows command line and a browser. The rest is fluff to start with.
First we need to set up the ‘app’ at SmartThings end, which is easiest using the CLI because it walks you through it. At this stage don’t bother with a target URL. That only gets used if you are into subscriptions and things. The redirect URL comes into play in the next section. At this point you are whitelisting valid URLs that you can use, just as you are whitelisting scopes that you are allowed to select.
> smartthing apps:create
? What kind of app do you want to create? (Currently, only OAuth-In apps are supported.) OAuth-In App
More information on writing SmartApps can be found at
https://developer.smartthings.com/docs/connected-services/smartapp-basics
? Display Name In search of highland cattle
? Description In which highland cattle are sought.
? Icon Image URL (optional)
? Target URL (optional)
More information on OAuth 2 Scopes can be found at:
https://www.oauth.com/oauth2-servers/scope/
To determine which scopes you need for the application, see documentation for the individual endpoints you will use in your app:
https://developer.smartthings.com/docs/api/public/
? Select Scopes. r:devices:*, w:devices:*, x:devices:*
? Add or edit Redirect URIs. Add Redirect URI.
? Redirect URI (? for help) https://httpbin.org/get
? Add or edit Redirect URIs. Finish editing Redirect URIs.
? Choose an action. Finish and create OAuth-In SmartApp.
Basic App Data:
─────────────────────────────────────────────────────────────────────────────────
Display Name In search of highland cattle
App Id cc425d75-ea53-4d68-84d4-230092e599d7
App Name ainsearchofhighlandcattle-0d972122-0280-4cf7-b72b-a309c0700cb0
Description In which highland cattle are sought.
Single Instance true
Classifications CONNECTED_SERVICE
App Type API_ONLY
─────────────────────────────────────────────────────────────────────────────────
OAuth Info (you will not be able to see the OAuth info again so please save it now!):
───────────────────────────────────────────────────────────
OAuth Client Id 0817f4d5-d764-4d09-a741-d5da52889b6c
OAuth Client Secret 9da0e5f8-80c9-4f35-a59f-16ba88774f62
───────────────────────────────────────────────────────────
At this point get the ID and secret copied somewhere.
Now move onto a browser and call this URL:
https://api.smartthings.com/oauth/authorize?client_id=0817f4d5-d764-4d09-a741-d5da52889b6c&response_type=code&redirect_uri=https://httpbin.org/get&scope=r:devices:*+w:devices:*+x:devices:*
See you are using the client ID here. You also need to specify a redirect URL. This has to be one that you whitelisted in the first stage and it has to be valid (it is checked). However it can be anything that it is polite to use. In this case https://httpbin.org/get is made available for looking at HTTP type stuff so it is fair usage.
If that works you should find yourself taken to the Samsung account login screen if you aren’t already logged in on your browser, where you can marvel at what an unbelievable mess they’ve made of their login flow. You will then get transferred back to something more obviously SmartThings in nature where you will get to select which Location you want to authorise. You will then get presented with a long list of tick boxes that allows you to fine tune the access you will have. Then when you are finished you are transferred to the redirect URL you specified. You aren’t interested in the content at this point, you are just looking for the URL to be:
https://httpbin.org/get?code=ZHUJGd
If it hasn’t all worked you’ll get a different query string. The code is all you care about though which is why you don’t need your own server at this stage.
You now need to trade your code for tokens. As you have both an ID and a secret you should use both. They get used in a bog standard Basic authentication which requires an authorization header using your client ID as your username and your client secret as your password. So here we can go back to a command line.
Curl will do the job. The -u creates the header for the Basic authentication and the -d creates a POST with the content type set to application/x-www-form-urlencoded,
curl -u "0817f4d5-d764-4d09-a741-d5da52889b6c:9da0e5f8-80c9-4f35-a59f-16ba88774f62" https://api.smartthings.com/oauth/token -d "grant_type=authorization_code&client_id=0817f4d5-d764-4d09-a741-d5da52889b6c&code=ZHUJGd&redirect_uri=https://httpbin.org/get"
Even though you aren’t being redirected anywhere you still need to supply one of your whitelisted redirect URLs.
All being well you will get a JSON response which will all be in one line but which I have tidied up.
{
"access_token":"5ec066a9-d108-4af4-9276-eedc850043d3",
"token_type":"bearer",
"refresh_token":"d4b93907-6bf8-46f0-8d14-ed007d5712c0",
"expires_in":86399,
"scope":"x:devices:* w:devices:* r:devices:*",
"installed_app_id":"e906cd16-b899-44d6-874a-e9d01b16e5b9",
"access_tier":0
}
You only get to change the code into tokens once. Nayely will be nodding knowingly at this point.
The end result is that you now have an access token. It still only lasts 24 hours and also this is a location level token which isn’t as much fun as the PAT, but it is likely to be all you need.
Now if you want to extend the life of this token you can. You’ll need the ID and secret for authentication and just the refresh token. Your refresh token will last thirty days. Again I’ll use curl on the command line.
curl -u "0817f4d5-d764-4d09-a741-d5da52889b6c:9da0e5f8-80c9-4f35-a59f-16ba88774f62" https://api.smartthings.com/oauth/token -d "grant_type=refresh_token&client_id=0817f4d5-d764-4d09-a741-d5da52889b6c&refresh_token=d4b93907-6bf8-46f0-8d14-ed007d5712c0"
Again a tidied up response:
{
"access_token":"b6c249e5-f942-405c-b152-d23ce336a947",
"token_type":"bearer",
"refresh_token":"416868bc-0ecc-4d87-b77d-a37e37bcbf51",
"expires_in":86399,
"scope":"x:devices:* w:devices:* r:devices:*",
"installed_app_id":"e906cd16-b899-44d6-874a-e9d01b16e5b9",
"access_tier":0
}
So that is a start. If you want to have SmartThings send you stuff then you need to have an app on a publicly available IP address and you have further hoops to jump through.
If you just want a PAT replacement then you are actually most of the way there as the access token does the same job (hopefully). If you have a script or app that uses the PAT then use the access token instead, but just be prepared to refresh the tokens first if they are getting too close to a day old.