Token Management

The access token obtained during the OAuth flow has a limited lifetime. Your app must refresh the token before it expires to maintain uninterrupted access to the SmartThings API.

Token Expiry

The access token expires after the number of seconds specified in the expires_in field of the token response (typically 86399 seconds, approximately 24 hours). After expiry, any API request using the expired token returns a 401 Unauthorized response.

Refreshing Tokens

Use the refresh token to obtain a new access token by making a POST request to the same token endpoint used during the initial code exchange.

Request

POST https://api.smartthings.com/v1/oauth/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: Basic {base64(clientId:clientSecret)}
Accept: application/json

grant_type=refresh_token&refresh_token={refreshToken}&client_id={clientId}

Parameter	Description
grant_type	Must be refresh_token
refresh_token	The refresh token from the most recent token response
client_id	Your app's Client ID

The Authorization header uses the same HTTP Basic authentication as the initial token exchange (Base64-encoded clientId:clientSecret).

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "access_token": "68e5657b-2892-4aa2-902b-3461116e6ea6",
  "token_type": "bearer",
  "refresh_token": "55a3a216-dffd-4478-91d0-ca0b5767606b",
  "expires_in": 86001,
  "scope": "r:devices:*",
  "access_tier": 0,
  "developer_account_id": "bcf8648b-b94b-43bf-aed8-8eac51fd866e",
  "installed_app_id": "11b9ea69-1399-43c4-bd4b-3166449ff8fb",
  "iot_account_id": "bcf8648b-b94b-43bf-aed8-8eac51fd866e",
  "owner_account_id": "bcf8648b-b94b-43bf-aed8-8eac51fd866e"
}

The response has the same structure as the initial token response. Both the access token and refresh token are new values -- your app must update its stored tokens with both new values.

Refresh Tokens are Single-Use Only

Once a refresh token is used, it is no longer valid.

Refresh Strategies

There are two common strategies for refreshing tokens:

Proactive Refresh

Refresh the token before it expires. Track the expires_in value from the last token response and refresh when the token is nearing expiry (e.g. when 75% of its lifetime has elapsed). This avoids any failed API calls due to expired tokens.

Reactive Refresh

Attempt the API call with the current access token. If the API returns a 401 Unauthorized response, refresh the token and retry the request. This is simpler to implement but means occasional API calls will fail on the first attempt. It can also cause problems if your app is making calls in parallel using the same token, since refreshing a token invalidates the old token.

A combination of both strategies provides the best reliability: proactively refresh when possible, but handle 401 responses as a fallback.

Token Storage

Tokens must be stored securely and durably:

• Encrypt at rest -- Access and refresh tokens grant access to the user's SmartThings devices and should be encrypted in your storage layer
• Associate with the installed app ID -- Store tokens keyed by installed_app_id so your app can retrieve the correct tokens for each user's installation
• Update atomically -- When refreshing, update both the access token and refresh token together to avoid inconsistent state
• Handle concurrent refreshes -- If your app has multiple processes or threads, ensure only one refresh request is in flight at a time for a given installed app.
• Clean up on uninstall -- When you receive a DELETE lifecycle event, delete the stored tokens for that installed app

Up Next

With access tokens securely stored, your app can begin calling the SmartThings API. Visit API Overview and Request Patterns for common request conventions. Alternatively, proceed to Retrieve Installed App & Location Details if you are ready to start interacting with the API.