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 enables 'Sign In with SmartHQ' and 'Register with SmartHQ' functionality to handle authorization (granting your app permission to control end-user's 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 Auth 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 Auth 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.

Registration Flow

For end-users who do not have a SmartHQ account, you can redirect those end-users to GET /oauth2/register in a web browser or webview to create one. See Implementation Recommendations below.

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) Chooses to create a SmartHQ account from your app
  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->>App: (8) Manually navigates back to your application
  User->>App: (9) Chooses to start authorization
  App->>Auth: (10) 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 from within your application interface.
2. Your application opens the SmartHQ sign-up page by GET /oauth2/register.
3. The SmartHQ Authorization Server displays a registration form to the end-user.
4. The end-user completes the form and submits it to create their SmartHQ account.
5. The SmartHQ Auth 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 Auth Server displays a confirmation screen upon successful email verification.
8. The end-user manually returns to your application (e.g., by navigating back or switching to your app’s browser tab).
9. The end-user initiates the authorization process from your app.
10. Your application calls GET /oauth2/auth to begin the OAuth 2.0 authorization flow.

Verification Screens UI

Displayed in step 5:

Displayed in step 7:

Implementation Recommendations

Currently, it is recommended to offer a registration and login link from within your app. Users with a SmartHQ account already can choose to log in with SmartHQ. Users without a SmartHQ account can choose to register with SmartHQ. After their registration, they can return to your app and log in with that new account.

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 commissioned device. - Received by calling POST /oauth2/token
Refresh Token	Used to get a new Access Tokens 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.

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 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-user's devices). While the user does login 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.