Documentation for OAuth

[AWGNelson (Nez)]

Hi,

Where is the best place to find the latest documentation and endpoints for an OAuth In SmartApp? I don’t think the authorize or token endpoints are listed anywhere but I could be wrong.

I think I have successfully created a SmartApp and set up the redirect URI. I’ve derived the authorize endpoint, and a user can log in, select the access they want to give, then submit. However I’m unsure if I have the correct endpoint to exchange the auth token for access and request tokens, because I’m getting a 401 code back.

Additionally, I left the “target url” field blank for the Smart App - would this impact anything?

Ultimately our Smart App only needs to be able to store and use tokens to execute commands on customer distributed devices periodically, on a CRON job type basis.

Thank you!
Alex

[Itati (SmartThing Developer Support)]

Hi Alex

1. The option to create OAuth integrations cannot be found in the Developer Workspace.
2. You need to use the SmartThings CLI to create this type of app

Command:
smartthings apps:create
---->The type you need to select is “OAuth-In App”
----> Target URL is the link where you want to receive the subscription events
----> These scopes are the permissions whitelisted from your app, if you use a scope in the “authorize URL” not included in your app’s scopes, you’ll get an error
-----> Add redirect URI because that’s where you’ll receive the authorization code once the user authorizes access to your app.3. 4.

3. You can also use the JSON in this sample as the input for the command.
   GitHub - SmartThingsCommunity/api-app-subscription-example-js: Example API Access SmartApp that shows the state and allows control of devices
4. Then, you need to start the OAuth 2.0 process which consists on:

a. Show the authorization page to the user by using this URL:
<https://api.smartthings.com/oauth/authorize?client_id=${clientId_from_app}&response_type=code&redirect_uri=${redirect_uri_from_app}&scope=${scopes_from_whitelisted_inApp}>
b. Once the user authorizes access to your app, it’ll redirect you to the “Redirect URI” you configured with the Authorization Code.
c. You’ll exchange this code for an Access Token. This is an example of that request:
curl -X POST "<https://api.smartthings.com/oauth/token>" -u "${clientId_from_app}":"${clientSecret_from_app}" -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=authorization_code&client_id=${clientId_from_app}&code=${codeReceived}&redirect_uri=${redirect_uri_from_app}"

5. The Access Token you get expires in 24 hours.
6. The Refresh Token expires in 29 days if not used. We suggest you refresh the token before this time, otherwise, you’ll lose the Refresh token and the User will need to re-authorize.

NOTE: Remember the OAuth integration has a limit of 500 installations by default. Each time a user authorizes access to one of his/her locations, it will count as 1 installation. This means, if a user has 3 locations and authorizes access to each of them, he/she will use 3 installations.

7. To refresh the Access Token, you need to use the same endpoint but the grant_type is different, here’s an example about this:

a.
curl -X POST “https://api.smartthings.com/oauth/token” -u “${clientId_from_app}”:“${clientSecret_from_app}” -H “Content-Type: application/x-www-form-urlencoded” -d “grant_type=refresh_token&client_id=${clientId_from_app}&refresh_token=${latest_refresh_token}”

`

[AWGNelson (Nez)]

Thank you, that’s comprehensive and exactly what I was looking for. I have the SmartApp working, however I haven’t set up the target_url yet - are there any other downsides aside from missing subscription events?

Do you have any further information on the criteria for increasing the limit of 500 installations? Is there a way to see what number the SmartApp is currently on.

[Itati (SmartThing Developer Support)]

Hi @AWGNelson

@AWGNelson

are there any other downsides aside from missing subscription events?

It shouldn’t affect functionality.

@AWGNelson

Do you have any further information on the criteria for increasing the limit of 500 installations?"

You can send an email to partners@smartthings.com for more detailed information on this topic. They should be able to assist you further!

Thanks!