Workspaces
Workspaces are the top-level resource in the Seam ecosystem. They encapsulate all other resources, such as devices, events, and connected third-party accounts.
Last updated
Workspaces are the top-level resource in the Seam ecosystem. They encapsulate all other resources, such as devices, events, and connected third-party accounts.
Last updated
© Seam Labs, Inc. All rights reserved.
A workspace is conceptually like a project or environment. It encapsulate all other Seam resources, such as devices and connected third-party accounts. You access resources within a workspace using an API key, a Personal Access Token (PAT), or client session tokens, and you can receive events from a workspace using webhooks.
There is no limit to the number of workspaces that you can create, but most Seam customers only have the following two workspaces:
One sandbox workspace in which they connect virtual devices to test their apps
One production workspace in which they connect real devices
Production workspaces enable you to connect and control real devices from brands, such as August, Schlage, Brivo, Nest, and more.
In the upper-right corner of the Seam Console, click the down arrow to display the workspace list.
Click + Add Workspace.
In the Add a Workspace dialog, type a name for your new workspace and your company name.
Disable Sandbox mode.
Click Create Workspace.
You can use either of the following two ways to connect devices to a production workspace:
Use the Seam Console.
Use Connect Webviews.
In the left navigation pane of the Seam Console, click Devices.
In the upper-right corner of the Devices page, click + Add Device. The Seam Console displays a Connect Webview (that is, an authorization flow) that enables you to connect a device account to Seam.
In the Connect Webview, click Continue.
In the manufacturer list, select the manufacturer of the devices that you want to connect.
Follow the login instructions to authorize these devices.
Once authorized, the devices associated with this test account appear in the Devices table in your production workspace.
If you are creating an application (app) to control your users' devices, use Connect Webviews. Connect Webviews are fully-embedded client-side components that you add to your app. Your users interact with your embedded Connect Webviews to link their device accounts to Seam through your app. Seam handles all the authentication steps. Once your user has completed the authorization through your app, your users' devices are linked with your production workspace, and you can access and control their devices using the Seam API.
Most Seam customers use a single production workspace to connect all their devices, regardless of whether these devices are ones that they own or they are controlling thousands of end customers' devices. For example, a property management app with thousands of customers could still use a single production workspace to connect all customers' devices.
Some Seam customers may be developing multiple apps, each of which needs to interact with devices. In this type of scenario, it may be useful to set up a different production workspace for each application.
For example, an information technology (IT) firm that builds custom apps for its customers will most likely want to create a separate workspace for each customer. This model can simplify security, support, and billing.
Occasionally, an app may also be using multiple Seam workspaces. For example, a restaurant chain providing a management dashboard for its franchisees may want to use a different Seam workspace for each franchisee to simplify billing and support. See App 3 in the following diagram:
Note that when you use multiple workspaces, you either need to create an API key for each workspace or create a single Personal Access Token (PAT) for use with all workspaces and then specify the ID of the workspace that you want to access.
Sandbox workspaces are a special type of workspace designed for testing code. Sandbox workspaces offer test device accounts and virtual devices that you can connect and control. This ability to work with virtual devices is quite handy because it removes the need to own physical devices from multiple brands.
Importantly, virtual devices behave identically to the corresponding real devices. That is, if your app works with a virtual device in a sandbox workspace, it will also work with a real device in a production workspace.
You can only connect virtual devices in a sandbox workspace. To connect a real device, switch to a production workspace.
In the upper-right corner of the Seam Console, click the down arrow to display the workspaces list.
Click + Add Workspace.
In the Add a Workspace dialog, type a name for your new workspace and your company name.
Enable Sandbox mode.
Click Create Workspace.
To connect virtual devices, specify the login credentials for test device accounts in the Seam Console or in Connect Webviews within you apps. All manufacturers and devices that Seam supports have one or more sandbox test accounts with pre-seeded devices. For login credentials for all test device accounts, see Sandbox Devices and Systems.
You can trigger test events for some virtual devices. This capability is useful for testing code that depends on receiving event notifications from the Seam API. For example, virtual noise sensor devices, such as Minut, provide the ability to trigger a "noise event" that emits an event to your webhook endpoint. Once you have triggered an event, you can view this even on the Events tab for the virtual device.
In the left navigation pane of the Seam Console, click Devices.
In the Devices table, click the device with which you want to interact.
Click the Actions tab. The Actions tab lists the actions that you can perform on this virtual device.
Click the desired action, as applicable for that action. For example:
For a virtual door lock, click the Locked toggle to lock or unlock the lock.
For a virtual thermostat, click Edit and then modify a climate setting.
For a virtual noise sensor, click Trigger to trigger a noise threshold alert.
Click the Events tab for the device. The Events tab displays the event.
To help you test your app against events—like device disconnection or removal—that are difficult to orchestrate in a QA environment using real devices, Seam provides a suite of simulate endpoints that you can use in a sandbox workspace. See Testing Your App Against Device Disconnection and Removal.
Sandbox workspace are unique in that you can reset them to the original starting state. For example, if you need to run complex continuous integration (CI) testing for an app, you can reset the sandbox workspace after each individual test run.
You can reset a sandbox workspace either manually through the Seam Console or programmatically using the Seam API. For detailed information about resetting a sandbox workspace through the Seam API, see the Reset Workspace API reference.
In the upper-right corner of the Seam Console, click the down arrow to display the workspace list.
Select the name of the sandbox workspace that you want to reset. The Seam Console switches to the selected sandbox workspace.
In the upper-right corner of the Seam Console, click the down arrow again.
In the workspace list, below the name of the selected sandbox workspace, click Reset.
You can add teammates to your workspace.
In the upper-right corner of the Seam Console, click the down arrow to display the workspace list.
Click the workspace that you want to share.
In the left navigation pane, click Team.
In the upper-right corner of the Team page, click + Add member.
In the Add Organization Member dialog, type the email address of the teammate that you want to add to this workspace.
Click Add to Team.
The Seam Console sends an email invitation to the specified teammate.
