API Access App Setup

Before your API Access App can interact with SmartThings, you must register your app with the SmartThings platform to obtain the credentials required for OAuth 2.0 authentication.

Prerequisites

• A Samsung account.
• A web server with a publicly accessible HTTPS URL (a tunneling tool like ngrok is a great tool for use during development).

App Endpoints

Your app should expose two HTTP endpoints. The endpoint paths below serve as examples; you will specify your actual endpoint URLs when registering your API Access App in the Console in a later step.

GET /oauth/callback (Required)

SmartThings redirects the user's browser to this endpoint after they authorize your app. The redirect includes an authorization code query parameter that your app exchanges for access and refresh tokens. See OAuth 2.0 Authorizationfor details.

POST / (Optional, Highly Recommended)

SmartThings sends webhook callbacks to this endpoint. These include: Device events -- Notifications when subscribed device attributes change (e.g. a switch turns on or off). Lifecycle events -- Notifications when the app is uninstalled or disconnected.

note

While registering a webhook endpoint is technically optional if your app only manually polls for device states without using subscriptions, it is strongly recommended. The webhook receives critical lifecycle events—such as when a user removes your app from their Linked Services via the SmartThings mobile app. Receiving this uninstall event allows you to perform necessary cleanup in your app, such as revoking and deleting persisted tokens and user data. See Webhook Events for details on the webhook payload format and request verification.

OAuth Scopes

Scopes define what your app is allowed to do. They follow the format {permission}:{resource}:{filter} where:

• permission -- The type of access: r (read), w (write), x (execute).
• resource -- The resource type, such as devices or locations.
• filter -- Which specific resources, or * for all.

For example, an app that reads location and device information, and controls devices would require the following permissions:

Scope	Description
r:locations:*	Read all locations.
r:devices:*	Read all devices.
x:devices:*	Execute commands on all devices.

These scopes are included in the OAuth authorization URL and are returned in the token response to confirm what was granted.

Available Scopes

Scope	Summary	Description
r:devices:*	Read one or all devices	Either read a specific device or read all devices associated with the auth token's principal.
r:devices:$	Read one device	Read a specific device or devices. If you specify this scope the user will be prompted to select one or more devices during the authorization process.
w:devices:*	Write one or all devices	Either write a specific device or write to all devices associated with the auth token's principal. If you specify this scope the user will be prompted to select one or more devices during the authorization process. Note that you only need this scope if you are going to delete or rename devices. Controlling devices requires an x:devices scope.
w:devices:$	Write specific device	Write a specific device.
x:devices:*	Execute one or all devices	Either execute a specific device or execute all devices associated with the auth token's principal.
x:devices:$	Execute specific device	Execute a specific device or devices. If you specify this scope the user will be prompted to select one or more devices during the authorization process.
r:hubs:*	Read one or all hubs	Either read a specific hub or all hubs associated with the auth token's principal.
r:locations:*	Read all locations	Read all locations associated with the auth tokens principal. Principal must be an installedapp or a user. User principal will have access to read locations associated to that user.
w:locations:*	Write all locations	Write all locations associated with the auth token's principal.
x:locations:*	Execute location	Change mode state on a location.
r:scenes:*	Read one or all scenes	Either read a specific scene or read all scenes associated with the auth token's principal.
x:scenes:*	Execute one or all scenes	Either execute a specific scene or execute all scenes associated with the auth token's principal.
r:rules:*	Read one or all rules	Read one or all rules associated with the auth token's principal.
w:rules:*	Write one or all rules	Write one or all rules associated with the auth token's principal.

Register Your API Access App

Your API Access App must be registered with SmartThings before your app can interact with the SmartThings platform. Register and manage your API Access Apps with SmartThings using the Developer Center Console.

To start the app registration process, visit the Console and select Service Integrations. Click Register New App.

During registration you will provide:

• App Display Name -- A publicly visible display name for your app.
• Redirect URIs -- The OAuth callback URL(s) for your app (e.g. https://your-app.example.com/oauth/callback).
• Target URL -- Your app's publicly accessible base URL (e.g. https://your-app.example.com).
• OAuth scopes -- The permissions your app requires (see above).

After registration you will receive three credentials:

Credential	Description
App ID	Unique identifier for your registered app.
Client ID	OAuth 2.0 client identifier.
Client Secret	OAuth 2.0 client secret (keep this confidential).

Verify Your Target URL

During app registration in the Console, you must verify ownership of your target URL.

1. Click Confirm Target URL in the Console to prompt SmartThings to send a verification payload.
2. Check your server logs for an incoming CONFIRMATION request structured like this:

{
  "messageType": "CONFIRMATION",
  "confirmationData": {
    "appId": "<your-app-id>",
    "confirmationUrl": "https://api.smartthings.com/v1/apps/<your-app-id>/confirm-registration?token=..."
  }
}

3. Copy the confirmationUrl from the request body and make an HTTP GET request to that URL. Alternatively, you can paste the URL directly into a browser.

Upon a successful request, your target URL status transitions from PENDING to CONFIRMED, enabling SmartThings to deliver webhook callbacks to your application.

tip

If you miss the initial confirmation request, you can re-send it from the Console, or trigger it via the SmartThings CLI:

smartthings apps:register [<your-app-id>]

Up Next

Once your app is registered and your endpoints are in place, you are ready to Implement the OAuth 2.0 Flow, enabling users to connect their SmartThings accounts.