SmartThings Homebridge Plugin with OAuth Support

A modern SmartThings plugin for Homebridge that provides seamless integration with your SmartThings devices. This plugin features automatic device discovery, OAuth authentication, and access token refresh capabilities.

Features

- No Legacy App Required: Works with the new SmartThings app and API
- Automatic Device Discovery: Automatically finds and adds your SmartThings devices
- Device Management: Automatically removes devices that are no longer in your SmartThings network
- OAuth Support: Secure authentication with automatic token refresh
- Easy Setup Wizard: New UI-based OAuth wizard - no tunnel required!

Prerequisites

Before you begin, ensure you have the following:

- Homebridge: A working Homebridge installation with UI access
- SmartThings CLI: Download and install the official SmartThings CLI tool

---

Installation Guide

$3

1. Open your Homebridge web interface (usually http://localhost:8581)
2. Go to the "Plugins" tab
3. Search for Homebridge Smartthings oAuth Plugin
4. Click "Install"

---

$3

You need to create a SmartThings OAuth application using the SmartThings CLI. This is a one-time setup.

1. Open a terminal/command prompt and run:
``bash
smartthings apps:create
`

2. Follow the prompts exactly as shown below:

| Prompt | What to Enter |
|--------|---------------|
| App Type | Select OAuth-In App |
| Display Name | Homebridge SmartThings (or any name you like) |
| Description | Homebridge integration |
| Icon Image URL | Press Enter to skip |
| Target URL | https://httpbin.org/get |
| Scopes | Select: r:devices:, x:devices:, r:locations:* |
| Redirect URI | https://httpbin.org/get |

> Important: Make sure to use https://httpbin.org/get for both Target URL and Redirect URI. This is what makes the wizard work without needing a tunnel!

3. Save your credentials immediately!

After creation, you'll see output like this:
`
OAuth Info (you will not be able to see the OAuth info again so please save it now!):
───────────────────────────────────────────────────────────
OAuth Client Id 7a850484-xxxx-xxxx-xxxx-xxxxxxxxxxxx
OAuth Client Secret 3581f317-xxxx-xxxx-xxxx-xxxxxxxxxxxx
───────────────────────────────────────────────────────────
`

> Critical: Copy and save both the Client ID and Client Secret somewhere safe. You cannot retrieve them later!

---

$3

Now open the plugin settings in Homebridge UI to complete the OAuth setup.

1. Go to your Homebridge web interface
2. Navigate to Plugins tab
3. Find "Homebridge Smartthings oAuth Plugin" and click the Settings (gear icon)
4. Click the "Open OAuth Setup Wizard" button

---

$3

The wizard has 4 steps:

#### Wizard Step 1: Enter SmartThings App Credentials
- Enter the OAuth Client ID from Step 2
- Enter the OAuth Client Secret from Step 2
- Click "Next"

#### Wizard Step 2: SmartThings Login
- Click "Next" - this will open a new browser window/tab
- You'll be taken to the SmartThings login page
- Log in with your Samsung/SmartThings account
- Select the location you want to use
- Click "Authorize" to grant permissions

#### Wizard Step 3: Copy the Authorization Code
After authorizing, you'll be redirected to httpbin.org which displays a JSON response like this:

`json
{
"args": {
"code": "hkp89A"
},
"headers": {
"Accept": "text/html,application/xhtml+xml,...",
"Host": "httpbin.org",
...
},
"origin": "xxx.xxx.xxx.xxx",
"url": "https://httpbin.org/get?code=hkp89A"
}
`

What to do:
1. Look for the "args" section at the top
2. Find the "code" value (e.g., "hkp89A")
3. Copy ONLY the code value (just hkp89A, without quotes)
4. Go back to the Homebridge wizard
5. Paste the code into the "Authorization Code" field
6. Click "Next"

#### Wizard Step 4: Save Configuration
- The wizard will automatically exchange your code for access tokens
- You'll see the Access Token and Refresh Token fields populated
- Click "Save Configuration"
- You'll see a success message

---

$3

After saving the configuration:
1. Go to the Homebridge main page
2. Click "Restart Homebridge"
3. Wait for Homebridge to restart
4. Your SmartThings devices should now appear in HomeKit!

---

You're Done!

Your SmartThings devices should now appear in HomeKit! The plugin will automatically:
- Discover all compatible devices
- Add them to HomeKit
- Remove devices that are no longer available
- Refresh access tokens automatically (no manual intervention needed)

---

Advanced: Webhooks for Real-Time Updates (Optional)

By default, the plugin uses polling to check device status every few seconds. If you want real-time device updates, you can configure webhooks so SmartThings pushes events directly to the plugin the instant a device changes state. Polling continues to run alongside webhooks as a fallback.

$3

When configured, the plugin:
1. Starts a webhook server on the configured port (default 3000)
2. Registers broad capability subscriptions with SmartThings so it receives device events in real-time
3. Continues polling as normal -- webhooks are purely additive, not a replacement

$3

- A publicly accessible URL that SmartThings can reach (via a tunnel service or port forwarding)
- Your SmartThings app must be registered as a Webhook SmartApp with the correct Target URL

$3

#### 1. Set up a secure tunnel

Use ngrok, Cloudflare Tunnels, or any reverse proxy to expose your Homebridge instance:

`bash
ngrok http --url=your-domain.ngrok-free.app 3000
`

Your public URL will be something like https://your-domain.ngrok-free.app.

#### 2. Create the SmartThings App with your webhook URL

When creating your SmartThings app (see Step 2 above), use your public tunnel URL instead of httpbin.org:

| Prompt | What to Enter |
|--------|---------------|
| Target URL | https://your-domain.ngrok-free.app (your public URL -- this is where SmartThings sends device events) |
| Redirect URI | https://your-domain.ngrok-free.app/oauth/callback (this is the OAuth callback endpoint) |

> Important: The Redirect URI must include the /oauth/callback path. This is the endpoint the plugin uses to complete the OAuth authorization flow. The Target URL should be your base URL without any path -- SmartThings will POST lifecycle events (PING, EVENT, etc.) to this root URL.

If you already created the app with httpbin.org, you can update it using the SmartThings CLI:
`bash
smartthings apps:update
`

#### 3. Update plugin configuration

In the Homebridge UI plugin settings:
- Set Server URL to your tunnel URL (e.g., https://your-domain.ngrok-free.app)
- Set Webhook Port to 3000 (or whichever port your tunnel points to)

#### 4. Restart Homebridge

After saving, restart Homebridge. Check the logs for:
- Webhook server listening on port 3000 -- the server started
- Successfully flushed existing subscriptions -- old subscriptions cleared
- Creating X broad CAPABILITY subscriptions... -- real-time subscriptions being set up
- SmartThings real-time subscriptions set up successfully. -- all done

$3

| URL | Purpose |
|-----|---------|
| https://your-domain.ngrok-free.app | Target URL in SmartThings app settings. SmartThings sends lifecycle events (PING, CONFIRMATION, EVENT) here. |
| https://your-domain.ngrok-free.app/oauth/callback | Redirect URI in SmartThings app settings. Used during OAuth authorization to receive the auth code. |

$3

After creating your SmartThings app and setting up the tunnel, fill in these fields in the Homebridge plugin settings:

| Field | Example | Description |
|-------|---------|-------------|
| Client ID | 7a850484-xxxx-xxxx-xxxx-xxxxxxxxxxxx | The OAuth Client ID from the smartthings apps:create output. |
| Client Secret | 3581f317-xxxx-xxxx-xxxx-xxxxxxxxxxxx | The OAuth Client Secret from the same output. Save this — you can't retrieve it later. |
| Server URL | https://your-domain.ngrok-free.app | Your public tunnel URL (the root, no trailing path). This tells the plugin to start the webhook server and register subscriptions. Leave empty if you only want polling. |
| Webhook Port | 3000 | The local port the webhook server listens on. Must match what your tunnel forwards to. Default is 3000. |

> Note: The Server URL is the same root URL you used as the Target URL when creating the SmartThings app. The plugin uses it both to start the local webhook server and to build the OAuth callback endpoint (/oauth/callback).

$3

Once webhooks are working, you can control which capabilities get real-time subscriptions (max 20) from the Homebridge UI — no restart required.

1. Open plugin settings in the Homebridge UI
2. Below the OAuth wizard button, you'll see the Real-Time Subscription Manager card
3. The card shows all capabilities discovered from your devices, sorted by device count
4. Check the capabilities you want subscribed in real-time (up to 20)
5. Click "Save & Apply Subscriptions" to flush the old subscriptions and create new ones immediately

Tips:
- Leave all unchecked to use automatic prioritization (most devices first)
- Use "Auto (by device count)" to quickly select the top 20
- The capability list refreshes each time Homebridge restarts and discovers devices
- Changes take effect immediately — no plugin restart needed

$3

"SmartThings subscriptions will not be set up"
- This means the plugin couldn't discover the installedAppId. Make sure your SmartThings app is installed to your location.
- If you see a 403 error, your OAuth token may not have sufficient scopes. Re-authorize through the wizard.

"Webhook server listening but no events arriving"
- Verify your tunnel is working by visiting your public URL in a browser
- Check that the Target URL in your SmartThings app settings matches your tunnel URL exactly
- SmartThings will send a PING challenge first -- check logs for Received SmartThings PING challenge

Events are working but some devices don't update in real-time
- SmartThings limits subscriptions to 20 per app. If you have more than 20 unique capabilities, lower-priority ones will remain polling-only. Check the logs for details on which capabilities are subscribed.

---

Troubleshooting

$3

"I don't see the OAuth wizard button"
- Make sure you have the latest version of the plugin (1.0.34+)
- Try clearing your browser cache and refreshing the Homebridge UI

"Authorization code is invalid"
- Make sure you copied only the code value, not the entire JSON
- The code expires quickly - try the authorization process again
- Ensure you're copying from args.code, not from the URL

"Plugin not finding devices after setup"
- Verify your SmartThings app has the correct scopes: r:devices:, x:devices:, r:locations:*`
- Make sure you selected the correct location during authorization
- Restart Homebridge after completing the wizard

"Devices not responding"
- Restart Homebridge
- Check that devices are online in the SmartThings app
- Check the Homebridge logs for error messages

$3

If you need to re-authenticate (e.g., tokens expired, changed SmartThings account):
1. Go to plugin settings
2. Click "Open OAuth Setup Wizard"
3. Complete all steps again
4. Restart Homebridge

$3

If you encounter issues:
1. Check the Homebridge logs for detailed error messages
2. Ensure all credentials are correct
3. Try re-running the OAuth wizard
4. Open an issue on GitHub

---

Changelog

See CHANGELOG.md for version history and detailed release notes.

Credits

This is a fork of the original homebridge-smartthings plugin created by @iklein99, enhanced with OAuth support, automatic token refresh, and the new OAuth Setup Wizard.