Authorization

To be able to control and monitor devices belonging to end-users through your app, the end-user must log in to SmartHQ and grant your app access to their SmartHQ devices. When you send a command to the end-user's device, you must show identification to prove you have access to control their device. This page discusses the OAuth 2.0 authorization framework for this purpose.

Prerequisites

• See Get Started for information on how to create an account, create an app, and begin calling our APIs.
• See our Device Commissioning documentation for details on connecting a device to the SmartHQ cloud and how that applies to your application.

General Info

The Identity and Access Management API is our OAuth 2.0 service used to generate access tokens for authorizing Digital Twin API calls that control and monitor end-user devices.

By default, SmartHQ’s Identity and Access Management API endpoints enable 'Sign In with SmartHQ' and 'Register with SmartHQ' functionality to handle authorization (granting your app permission to control end-users' devices). The endpoints are not intended to perform user authentication for your application as a way for an unauthenticated user to gain access to your application. See Authorization vs Authentication to learn more.

End-to-End Flow

This sequence diagram explains how the end-user gives your application access to control and monitor their devices. As a result, your application receives an access token to approve future API calls.

sequenceDiagram
  participant App as Your Application
  participant User as End-User
  participant Auth as SmartHQ Auth Server
  participant API as Digital Twin API

  User->>App: (2) Chooses to start authorization
  App->>Auth: (3) GET /oauth2/auth
  Auth->>User: (4) Displays login & consent screen
  User-->>Auth: (5) Logs in & grants permissions
  Auth-->>App: (6) Redirects with Authorization Code
  App->>Auth: (7) POST /oauth2/token (with Auth Code & additional parameters)
  Auth-->>App: (8) Returns Access Token (and optional Refresh Token)
  App->>API: (9) API call with Access Token
  API-->>App: (10) API gives response
  App->>Auth: (11) POST /oauth2/refresh_token (with Refresh Token)
  Auth-->>App: (12) Returns new Access Token
  User->>App: (13) Chooses to log out
  App->>App: (14) Logs user out locally
  App->>Auth: (14) Redirects to GET /oauth2/applogout
  Auth->>App: (15) Redirects to callback URL specified in app creation

1. You create an account and create an app in the SmartHQ ecosystem to obtain your Client ID and Client Secret.
2. The end-user interacts with your application and initiates the authorization process.
3. Your application calls GET /oauth2/auth with query parameters specified in the OpenAPI specification. Optionally, to obtain a Refresh Token later, include access_type=offline.
4. The SmartHQ Authorization Server returns a SmartHQ login web page to the end-user.
5. The end-user logs in to SmartHQ. The end-user is presented with an authorization screen to grant your app permission to access their devices and authorizes your application.
6. The SmartHQ Authorization Server redirects the end-user back to the Callback URL specified when creating the SmartHQ app, passing the Authorization Code as part of the URL.
7. Your application calls POST /oauth2/token with the Authorization Code and additional parameters in the request body.
8. The SmartHQ Authorization Server returns an Access Token. If a Refresh Token was requested and granted, it is included in the response.
9. Your application calls any endpoint in the Digital Twin API, including the Access Token as a Bearer token in the Authorization header to authorize the request.
10. The Digital Twin API responds to your application.
11. Your application, when the Access Token expires, calls POST /oauth2/token with the Refresh Token and other required parameters to obtain a new Access Token without requiring the end-user to reauthorize.
12. The SmartHQ Authorization Server returns a new Access Token to your application.
13. The end-user chooses to log out of your application.
14. Your app logs the end-user out locally and redirects them to GET /oauth2/applogout in the browser to clear the cached SmartHQ login.
15. The end-user is redirected to the callback URL specified when creating the app in the SmartHQ Developer Portal.

Authorization Flow

The authorization flow begins with calling GET /oauth2/auth in step 3 in the sequence diagram above. This endpoint returns HTML for a login page, which after logging in, presents the end-user with an authorization screen to give your app permissions to control and monitor their appliances. The authorization flow finishes with step 6 by redirecting the end-user back to your application with the authorization code as part of the redirect url.

Registration Flow

For end-users who do not have a SmartHQ account, GET /oauth2/register is an API endpoint that allows users to do the following:

• Sign up for SmartHQ by creating a SmartHQ account
• Verify their account through email
• Sign in to their SmartHQ account¹
• Approve your application to control and monitor their devices
• Go back to your application by SmartHQ redirecting.²

This endpoint functions just like GET /oauth2/auth with an additional step at the start to create an account.

Implementation Recommendation

It is not necessary to include GET /oauth2/register directly within your application. All users can be directed to GET /oauth2/auth. If needed, they can choose to create a SmartHQ account from that page- they will be automatically redirected to GET /oauth2/register when they choose to sign up for a new account. The query parameters will carry over from GET /oauth2/auth to GET /oauth2/register.

Providing users with a single link for authorization (GET /oauth2/auth) reduces complexity, but allows both returning and new users to complete the authorization process.

Note

Even if an end-user creates a SmartHQ account through this registration flow, they must still download the SmartHQ app to complete device commissioning for the device to appear in the SmartHQ cloud and be accessible via our APIs.

sequenceDiagram
  participant App as Your Application
  participant User as End-User
  participant Auth as SmartHQ Auth Server

  User->>App: (1) End-user chooses to create a SmartHQ account
  App->>Auth: (2) GET /oauth2/register
  Auth->>User: (3) Displays sign-up screen
  User-->>Auth: (4) Signs up
  Auth->>User: (5) Displays verify your email screen
  User-->>Auth: (6) Verifies email
  Auth->>User: (7) Displays confirmation screen
  User->>Auth: (8) End-user selects "I've Verified My Email"
  Auth->>User: (9) GET /oauth2/auth

(See End-to-End Flow sequence diagram above for where this diagram leaves off)

1. The end-user chooses to create a SmartHQ account: either directly from you providing a link to GET /oauth2/register, or the end-user choosing to sign-up from a URL in the GET /oauth2/auth returned webpage (recommended approach).
2. GET /oauth2/register gets called.
3. The SmartHQ Authorization Server displays a registration form to the end-user.
4. The end-user completes the form to create their SmartHQ account.
5. The SmartHQ Authorization Server presents a screen prompting the user to verify their email address.
6. The end-user clicks the link in their email to verify their SmartHQ account.
7. The SmartHQ Authorization Server displays a confirmation screen upon successful email verification.
8. The end-user selects the button "I've Verified My Email" from the first "verify your email screen."
9. Upon clicking the "I've Verified My Email" button, GET /oauth2/auth is automatically called which displays the SmartHQ login screen to end-user.
10. See End-to-End Flow Sequence Diagram for where this continues. The user proceeds with step 4 in that diagram.

App Logout Use Case

See steps 13-15 in the sequence diagram above.

The authorization process opens SmartHQ login pages in a browser or webview as part of the OAuth 2.0 flow. SmartHQ stores a session via browser cookies to remember which end-user was last signed-in. If your app logs out end-users but does not clear that SmartHQ session, the next time the login flow is triggered, the end-user may be automatically logged in with the same SmartHQ account, even if they were expecting to switch to a different account.

The purpose of POST /oauth2/applogout is to remove the cached login session (i.e., SmartHQ user session) stored in the end-user's web browser. That means next time they try to authorize something, they’ll be prompted to log in again, rather than being auto-logged-in with their last account.

Important

To ensure a complete logout experience and prevent automatic re-login with the previous account, your app should always invoke this endpoint as part of its logout flow.

What this endpoint does not do:

• This endpoint does not revoke tokens. Any access or refresh tokens your app receives from SmartHQ are still valid. You can continue making API calls unless you manually stop using the token.
• This endpoint also does not end the user's session within your app. You’re still responsible for logging the end-user out on your side.

Client Credentials

When creating an app on the SmartHQ Developer Portal (see Get Started), you receive two important pieces of information:

Credential	Purpose	Usage
Client ID	Uniquely identifies your app to the SmartHQ authorization server	Included in OAuth requests to indicate which app is making the request
Client Secret	Verifies your app to the authorization server	Used in POST /oauth2/token to securely obtain access tokens

OAuth 2.0 Tokens

OAuth 2.0 authorization involves different credentials, each serving a different purpose:

Credential	Purpose	Key Details
Authorization Code	Temporary code received after user authorization to get an access or refresh token	- Single-use - Valid for 10 minutes - Used to request Access & Refresh Tokens. - Received by calling GET /oauth2/auth or GET /oauth2/register
Access Token	Authorizes SmartHQ API requests by being passed as the bearer token	- Reusable - Valid for 1 hour - Tied to a single end-user's SmartHQ account. The access token gives access to the end-user's devices through our APIs. - Received by calling POST /oauth2/token
Refresh Token	Used to get a new Access Token without requiring additional user login	- Reusable - Valid indefinitely, until a new token is requested; the new token then becomes only valid refresh token. - Only issued when access_type=offline is called in GET /oauth2/auth or GET /oauth2/register. - Received by calling POST /oauth2/token

Note

• Each access token corresponds to a single end-user's account. The access token only provides access to the device the end-user has commissioned to their SmartHQ account.
• None of the Identity and Access Management API endpoints require an access token to be used.

Callback URL

The Callback URL is specified when creating an app in the SmartHQ ecosystem. It is where end-users are redirected after they grant permission to your application. This URL should be part of your application; it is where your application will receive the authorization code, which can then be exchanged for an access token.

Modify Callback URL

The Callback URL can be changed in the SmartHQ Developer Portal by going to the APIs page, selecting the "Apps" menu option, choosing your app, and clicking "Edit" next to the "Credentials" tab.

Callback URL vs. redirect_uri

The callback URL you specify when creating a SmartHQ app is referred to as the redirect_uri in the Identity and Access Management API specification. redirect_uri is an OAuth 2.0 term for the callback URL. Both refer to the same destination—where the end-user is redirected after authorization—and must be the exact same URL.

Authorization vs. Authentication

SmartHQ’s Identity and Access Management API endpoints handle authorization (granting your app permission to control end-users' devices). While the user does log in to SmartHQ to complete this authorization, the API is not intended to perform user authentication. This means your application should not rely on the Identity and Access Management API to sign in users to your application. You’ll still need your own login system or another OpenID Connect (OIDC) provider to allow users to sign into your application.

However, if your application would benefit from the ability to authenticate with SmartHQ, please contact us.

---

1. Here the user is automatically redirected to GET /oauth2/auth with the same query parameters used in the original GET /oauth2/register request. ↩

2. SmartHQ includes the authorization code as part of the URL. ↩