Skip to main content
Developer DocumentationCertify and Publish Your DeviceSmartThings APIEnterprise API
Developer Documentation

Get Started With the Enterprise API Playground

important

The Enterprise API is exclusively for SmartThings Pro customers with a signed agreement. You must have an existing SmartThings Enterprise Service Account in order to use the Enterprise API.

The Enterprise API Playground is an interactive environment that allows you to execute requests against select Enterprise API endpoints directly from your browser. It connects to your active SmartThings Enterprise resources, enabling you to query, view, and analyze real data in real-time.

Use the Playground to:

  • Prototype Faster: Skip the boilerplate code and interact immediately with our features.
  • Verify Permissions: Test calls against your actual data hierarchy.
  • Inspect Payloads: Understand response schemas and troubleshoot edge cases before coding.

Prerequisites​

Before you can interact with the live data in the Playground, ensure you have the following:

  • A SmartThings Enterprise Service Account: Access to the Playground is restricted to organization-level accounts. Standard consumer SmartThings accounts do not have permission to query the Enterprise API.
  • A Valid API key: You will use your API key to obtain a short-lived JWT. Your Service Account credentials are used to generate an intermediate API Key. Your account manager will assist you with this process. Contact us at b2bpartners@smartthings.com if you do not yet have your API key.
tip

Your Service Account’s API key credentials act as the bridge between the Playground and your organization's data. Ensure your Service Account has the appropriate roles selected for the resources and endpoints you wish to test. If a call returns a 403 Forbidden error, check your API key permissions first.

About the Enterprise Authorization Flow​

To ensure secure access to your organization's data, the Enterprise API uses a specific authorization flow:

  1. Service Account: Authorization starts with your Service Account credentials.
  2. API Key: Your Service Account credentials are used to generate an intermediate API Key. Your account manager will assist you with this process.
  3. Access Token: Your API key is then used to generate the final Access Token required to make API calls.
Obtaining Your API Key

Obtaining your API key is part of the onboarding process when joining SmartThings Enterprise. If you are an existing SmartThings Enterprise partner and have not received your API key, please contact your account manager or reach out to us at b2bpartners@smartthings.com.

After obtaining your API key, you are ready to generate an access token and interact with the API playground.

Exchange your API Key for an Access Token​

To ensure security, the Enterprise API does not accept your API Key directly. Instead, you must exchange it for a temporary Access Token (JWT).

The next page (Acquire a token using an API key) provides an interactive request/response component, allowing you to exchange your API key for an access token.

  1. Navigate to Acquire a token using an API key.
  2. Paste your API key into the Request input field labeled Bearer Token. The default token life is 1 hour. Request a duration of up to 24 hours by setting an expiresInSec value in the request body.
  3. Click Send API Request.
  4. Copy the generated token from the response body - be sure to copy the full token! This token will allow you to interact with the Enterprise API.
Quick Copy

Click the key icon in the response body to instantly copy the full access token.

Using Your Token​

Once you have your token, select any endpoint in the Playground and paste your token into the Authorization header. The responses will contain real-time data directly from your SmartThings Enterprise account.