We’re working through the final writing of the docs for this. We’ll need to edit/review, so it will probably be a couple days yet. But here’s a summarized/just-the-facts rundown preview for you. Docs will be coming soon, but figured the sooner people know the better. Much of this info isn’t new and has been helpfully shared by @tgauchat (thanks Terry!), but there are a few subtle changes worth noting.
TL;DR
Use https://graph.api.smartthings.com to get the access code, token, and endpoints. Then use the returned uri and append any paths to it to make calls.
More details below:
Get Authorization Code
GET https://graph.api.smartthings.com/oauth/authorize?
response_type=code&
client_id=YOUR-SMARTAPP-CLIENT-ID&
scope=app&
redirect_uri=YOUR-SERVER-URI
This will require the user to log in with their ST credentials, choose a Location, and select what devices may be accessed. An authorization code will be returned that lasts for 24 hours.
Note that when a location is chosen, SmartThings will attempt to find a SmartApp with the requested client ID on the specific server associated with that location. If one cannot be found, it will fail to load the devices, with a message about no SmartApp being found for that client ID. This is what is happening with SmartApps that are not published to all servers, or if they are using client IDs/secrets for a different server.
Get Access Token
Use the authorization code, along with the client ID and secret, to get the access token.
POST https://graph.api.smartthings.com/oauth/token
The following parameters should be sent on the request:
-
grant_type: use “code” for this flow.
-
authorization_code: this is the authorization code obtained from the previous step.
-
client_id: this is the client id of the SmartApp. It is the identifier for the SmartApp.
-
client_secret: the OAuth client secret of 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.
GET requests to https://graph.api.smartthings.com/oauth/token will also work, but POST is preferred.
That will return a response like:
{
"access_token": "XXXXXXXXXXX",
"expires_in": 1576799999,
"token_type": "bearer"
}
The token is long-lived (50 years) and doesn’t support refresh tokens. Refresh tokens will be supported in a future release.
The access token should be kept securely by the third party.
Get SmartApp Endpoints
Using the access token, get the endpoint for the SmartApp:
GET -H "Authorize: Bearer ACCESS-TOKEN" "https://graph.api.smartthings.com/api/smartapps/endpoints"
A successful response will look like this (we will probably remove sending back the client secret soon, and the url is there for legacy purpose - use the uri):
{
"oauthClient": {
"clientSecret": "CLIENT-SECRET",
"clientId": "CLIENT-ID"
},
"uri": "BASE-URL/api/smartapps/installations/INSTALLATION-ID",
"base_url": "BASE-URL",
"url": "/api/smartapps/installations/INSTALLATION-ID"
}
Make API Calls
Use the uri to make REST calls, appending any path mappings for your specific SmartApp. Previously, we could just assume the SmartApp was installed on https://graph.api.smartthings.com, and we would append the url to it. Now, because the SmartApp may be installed on different servers for different locations, the uri should be used.
I hope that helps people even though the docs aren’t finalized yet, thanks for being patient 
