Glossary
SmartHQ uses several terms and domain-specific language that may be unfamiliar to some readers. This page defines and clarifies key terms as they are used in the context of the SmartHQ APIs.
Access Token¶
A credential used to authorize API requests. This credential is passed as a bearer token to the Digital Twin API and is obtained through the OAuth flow.
Adapter¶
A special OAuth application in the SmartHQ system. This is a server-side application that manages multiple gateways of a single type. It is also responsible for routing outbound requests to its gateways.
Alert¶
A notification indicating a specific condition or event related to a device, such as a cycle completing (cloud.smarthq.alert.endofcycle).
AlertType¶
The JSON key used to identify an alert in API requests and responses ("alertType": "cloud.smarthq.alert.pausedcycle").
API¶
An interface that allows software applications to communicate with each other. APIs define the methods, inputs, and outputs required to access SmartHQ functionality securely and reliably.
App (Application)¶
Software—typically mobile or web-based—that integrates with SmartHQ APIs to access and control devices on behalf of an end-user. In the Developer Portal, creating an app provides the credentials needed to connect your software to the SmartHQ system. The Developer Portal app mirrors and represents the actual application you're building or built.
AppId¶
A unique identifier assigned to a SmartHQ application when the application is created on the SmartHQ Developer Portal.
Appliance¶
A physical product, such as a refrigerator, oven, or washer. For SmartHQ compatibility, an appliance must have an internet connection.
AsyncAPI¶
A specification for documenting asynchronous APIs, particularly those using event-driven architectures like Pubsub. Used to describe SmartHQ's Event Stream API.
Asynchronous¶
A communication pattern in which a message is sent without being directly requested. In SmartHQ, events defined by the Event Stream API, such as device alerts or device state changes, are delivered asynchronously via WebSocket or callback.
Authentication¶
The process of verifying the identity of a user attempting to access SmartHQ services.
Authorization¶
The process of determining whether a user or developer has permission to access a specific resource or perform an action.
Authorization Code¶
A temporary code issued during the OAuth 2.0 flow that a client exchanges for an access token.
Authorization Header¶
An HTTP header used to transmit authorization credentials, such as a Bearer token, in API requests.
Bearer Token¶
A type of access token used in the Authorization header to authenticate API requests. It grants access to SmartHQ resources on behalf of an end-user.
Callback¶
A delivery method where SmartHQ sends a message or authorization code to a developer-defined URL.
ClientId¶
A public identifier issued to each application integrating with SmartHQ. It is used during OAuth flows to identify the calling app.
ClientSecret¶
A confidential key associated with a ClientId, used to authenticate the application during OAuth flows.
Command¶
A request to a device to execute an action as defined by a service.
Commissioning¶
The process by which a device owner connects their device to Wi-Fi and links it to their SmartHQ account, enabling remote control and monitoring.
Configuration¶
The service configuration contains properties specific to the service type, which define its boundaries, such as supported modes for the mode service or max/min temperatures for the temperature service.
Data Model¶
The structured representation of SmartHQ services, devices, and states, including their properties, relationships, and valid values.
Developer Portal¶
The central website for developers to explore SmartHQ APIs, create apps, get credentials, and access documentation.
Device¶
A connected appliance or sensor that is registered and managed through a gateway—such as a washing machine, light bulb, or door sensor. Each device consists of one or more services that define its capabilities and interactions.
Domain¶
In SmartHQ, a domain indicates where in a device a service is located. It can also be used to specify the purpose of a device or sub-device.
DomainType¶
The JSON key used to identify a domain in API requests and responses ("domainType": "cloud.smarthq.domain.laundry").
End-User¶
A device (appliance) owner who gives a SmartHQ application access to their devices.
Gateway¶
The entity that exposes an end-user's devices and makes calls to the Device API on behalf of devices. A gateway is registered to a single end-user account and corresponds to a single adapter type. A gateway can be either physical (e.g., Kitchen Hub) or virtual. Every entity in this architecture MUST contain a gateway that interfaces with an adapter. For example, a single device, like a washing machine, will have a logical gateway that handles the connection to the adapter and exposes the device(s).
HTTPS Callback¶
A method of event delivery where SmartHQ sends HTTP POST requests to a secure client-defined URL in real time when device events occur.
Machine Name¶
The name of the app created in SmartHQ. This name is shown to end-users who authorize an app to control and monitor their devices.
OAuth¶
An open standard for secure authorization. SmartHQ uses OAuth 2.0 to allow developer apps to request access to user devices without handling user credentials directly.
OpenAPI¶
A specification for documenting RESTful APIs that SmartHQ uses for many of its APIs on the Developer Portal.
Postman¶
A popular tool for calling APIs. SmartHQ provides instructions to help developers explore their APIs and start making API calls quickly.
Provisioning Token¶
A credential used to connect a gateway to a SmartHQ account. This credential is generated by the /v2/gateway Digital Twin API endpoint and is exchanged for a Gateway Access Token through the Device Adapter API.
Refresh Token¶
A long-lived credential that can be passed to the Identity and Access Management /oauth2/token endpoint to gain a new access token without requiring the end-user to reauthorize.
Register (Registration)¶
The process of creating an account in SmartHQ. This is a necessary step in gaining access to the SmartHQ Developer Portal.
Service¶
A feature available on a device that can communicate properties, states, and receive commands. Services have a supportedCommands property that defines the list of commands a client can run on a service (as long as the disabled state is not true).
Service Alerts¶
Alerts in the SmartHQ system that pertain to errors devices face, such as cloud.smarthq.alert.fault.defrost.abnormal.
ServiceDeviceType¶
The JSON key used to identify a serviceDevice in API requests and responses ("serviceDeviceType": "cloud.smarthq.device.dryer").
ServiceId¶
A unique identifier for a particular service. This can be used in the Digital Twin API to get information about a service.
ServiceType¶
A serviceType is an archetype for the behavior of a certain feature (e.g., toggle [on/off], mode, integer, etc.).
SmartHQ¶
A connected appliance ecosystem by GE Appliances that allows users and third-party apps to remotely monitor, control, and automate smart devices.
SNS Callback¶
A delivery method where SmartHQ publishes events to an Amazon SNS topic. The SNS topic then forwards the events to client-subscribed endpoints.
State¶
The state of a service describes its current status, for example, on/off for a toggle service or the current mode for a mode service.
Synchronous¶
A communication pattern where a client sends a request and waits for a response. In SmartHQ, this applies to all APIs except the Event Stream API.
Tuple¶
For each service of a device: (serviceType, domainType, and serviceDeviceType). The combination of serviceType, domainType, and serviceDeviceType describes the specific feature (e.g., serviceType = toggle, domain = sound, serviceDeviceType = appliance will turn on and off the sound when buttons are pressed).
WebSocket¶
A real-time, bidirectional communication channel between an app and SmartHQ, used for receiving live device updates and configuring subscriptions.