How to connect a smart lock to your app

Create a workspace in Seam Console, generate an API key under Developer > API Keys, and export it as SEAM_API_KEY. Start in a sandbox workspace: it comes with virtual locks, so you can run this whole flow before touching real hardware.

1npm i seam
2
3# The SDK picks this up automatically.
4export SEAM_API_KEY=seam_test_your_sandbox_api_key

One call from your backend. accepted_providers narrows the brand list to what your product supports; leaving it off shows every stable brand. The response carries a url for your user and a connect_webview_id you keep, because the id is how you find out what happened after they finish.

1const connectWebview = await seam.connectWebviews.create({
2  // Only the brands your product supports. Omit this to show all stable brands.
3  accepted_providers: ["schlage", "yale", "august", "smartthings"],
4  // Where the webview sends the user when they finish.
5  custom_redirect_url: "https://example.com/locks/connected",
6})
7
8// Store the id so you can verify the outcome after the redirect.
9console.log(connectWebview.connect_webview_id)
10console.log(connectWebview.url)

Open the url in an iframe or a new window. Your user picks their brand and signs in with their own account. Seam runs the credential validation and any multifactor step, and sends them to your custom_redirect_url when the connection is made. Their password never passes through your servers, which keeps that login out of your security scope.

Fetch the webview by id. status authorized with login_successful true means the account is connected, and connected_account_id scopes a device list to exactly what this user linked. Read the capability flags off each device before you offer actions in your UI: a lock that cannot take codes should never show a PIN screen.

1const finished = await seam.connectWebviews.get({
2  connect_webview_id: storedConnectWebviewId,
3})
4
5// "authorized" and login_successful arrive together when the user completes
6// the flow. Anything else means they closed it or the login failed.
7if (finished.status === "authorized" && finished.login_successful) {
8  console.log(finished.connected_account_id)
9}

Accounts change after onboarding: locks get added, batteries die, someone renames the front door. Re-list devices on a schedule or subscribe to device lifecycle events with a webhook, and treat the device list as state you sync instead of a one-time import.

1const devices = await seam.devices.list({
2  connected_account_id: finished.connected_account_id,
3})
4
5// Capability flags tell you what each lock can do before you offer it in
6// your UI. true works today, false means blocked right now, absent means
7// the model never does it.
8for (const device of devices) {
9  console.log(
10    device.display_name,
11    device.can_remotely_unlock,
12    device.can_program_online_access_codes,
13  )
14}