How to use refresh tokens

A refresh token and access token pair is provided to a SmartApp during the INSTALL and UPDATE lifecycles.

Once the access token has expired, the refresh token enables the SmartApp to obtain a new access token.

Step 1: Understand when to use refresh tokens

Be aware of the following expiration times:

  • An access token expires in 24 hours.
  • A refresh token expires in 30 days.

A refresh token is invalidated after being used to successfully obtain a new access token.

You will receive a 401 Unauthorized status code when attempting to use an expired refresh token.

Step 2: Obtain your client ID and client secret

You need your client ID and client secret to call the API to obtain a refresh token.

If you don't know the client ID and client secret of your SmartApp, you can view the client ID and generate a new client secret by logging into Developer Workspace and selecting the SmartApp from your list of Automations or Device Integrations.

Step 3: Call the token API

You can now call the API to get a new refresh token. Authorization and permissions details the required parameters.

Below is an example request showing the headers:

curl -X POST \
  https://auth-global.api.smartthings.com/oauth/token \
  -H 'Authorization: Basic Q0xJRU5UX0lEOkNMSUVOVF9TRUNS...' \
  -d 'grant_type=refresh_token&refresh_token=9f281234-ffff-ff46-679d-11f6bcbeea08'

The Authorization: Basic header is a Base64 encoding of the following string: clientId:clientSecret (replace clientId and clientSecret with your own values).

Step 4: Keep your token secure

The refresh token must be confidential and handled securely.

What's next