Skip to main content

Client to Cloud Communication

All communication between clients and the ESP RainMaker cloud happens over HTTP REST APIs. Most APIs require users to log in first. The REST API details can be found in the Swagger documentation. Below is a brief summary of available APIs categorized by the user roles of ESP RainMaker: end user, admin user, and Superadmin user.

What is a client?

A client refers to different entities, including phone apps, CLI, dashboard, Alexa/GVA, etc.

  • Phone apps and Alexa/GVA are relevant to end users.
  • Dashboards and CLI are relevant to admin/Superadmin users.

It is worth noting that all admin user APIs listed here are also accessible to Superadmin users. However, APIs listed for Superadmin users are exclusively available to them.

APIs for All Users​

tip

The APIs listed below are relevant to both end users and admin/Superadmin users.
How these APIs are relevant to specific user types is elaborated in the dropdowns below.

User Management

These APIs are implemented in phone apps for end users, admins, and Superadmins, and in the CLI and dashboards for admins and Superadmins.

  • Sign up using an email address, password, and a one-time verification code.
  • Log in using an email address and password or third-party ID providers like Google, Apple, or WeChat.
  • Log out of the session.
  • Delete a user account.
  • Fetch details of the current user account.
  • Update a user account's name and phone number.
  • Change/forget the password.

APIs for End Users​

Node Management
  • User Node Association (Associating a node with the user).
  • Node Parameter Operations (Update or retrieve the state of the node).
OTA Service
  • Enable end users to upload new firmware images.
  • Retrieve the latest OTA update for nodes associated with the user.
  • Push OTA updates to nodes.
  • Fetch the latest status of OTA updates for nodes associated with the user.
Device Grouping
  • Create, update, share, or fetch user device groups.
  • Share node groups between users.
Time-Series Data/Simple Time-Series Data
  • Retrieve Time-Series data.
  • Retrieve simple Time-Series data.
Custom User Data
  • Retrieve or store custom user data.
Event Filter for Users
  • Manage event filtering information related to integrations for users.
Mobile Platform Endpoint (Push Notifications)
  • Create, fetch, or remove mobile platform push notification configurations.
Automation Trigger and Actions
  • Add, update, retrieve, or remove automation triggers and actions.
Command-Response Communication
  • Retrieve or add Command-Response requests.
OAuth in RainMaker (For OAuth-only Deployments) (Beta)
  • Initiate the OAuth2 flow (Beta).
  • Retrieve an authorization code.
  • Obtain authorization tokens for users.
External API Passthrough Service
  • Fetch external API configurations.
  • Retrieve data from external APIs.
  • Make POST requests to external API endpoints.
User Public Profile
  • Retrieve a user's public profile.
  • Add or update a public profile.
IoT Endpoint (API to Fetch IoT Endpoint)
  • Retrieve the IoT endpoint (MQTT host URL).

APIs for Admin Users​

OTA Service
  • Upload new firmware images.
  • Retrieve details about OTA images.
  • Delete OTA images for users.
  • Archive or unarchive OTA images.
  • Obtain pre-signed URLs to upload firmware images or packages to S3.
  • Confirm the upload of firmware images or packages.
  • Create new OTA jobs.
  • Retrieve details about OTA jobs.
  • Cancel or archive OTA jobs.
  • View OTA job statuses.
  • View summaries of OTA jobs.
  • Get pre-signed URL to upload the firmware package.
  • Upload new packages containing firmware images.
Device Grouping
  • Create, update, retrieve, or delete admin device groups.
Time-Series Data/Simple Time-Series Data
  • Retrieve Time-Series data.
  • Retrieve simple Time-Series data.
Webhook Integration
  • Retrieve user node webhook integration information.
  • Add, update, or delete webhook user node integrations.
Event Filter
  • Retrieve user node webhook integration information.
  • Add, update, or delete webhook user node integrations.
Roles and Policy Manager
  • Add, update, retrieve, or remove policies.
  • Add, update, retrieve, or remove roles (role-based assignment and access control).
User Role Mapping
  • Assign or remove roles for users.
  • Add, update, retrieve, or remove roles (role-based assignment and access control).
Command-Response Communication
  • Retrieve or add Command-Response requests.
API Information
  • Retrieve available API endpoints and methods.
Tag Management
  • Retrieve tag-related data for various resources.
  • Retrieve tag names and values attached to various resources.
  • Attach or detach tags to various resources.
Secure Sign

APIs used to securely sign OTA images with signing keys and retrieve logs of signing requests.

  • Securely sign OTA images (firmware) and associated bootloader files.
  • Retrieve secure signing request statuses.
  • Retrieve images signed by a given key.
  • Retrieve keys used to sign a given image.
Key Management
  • Create new keys.
  • Retrieve details and digests of keys.
User-Specific Data Management for Admin Users (Customer Deployments Only)
  • Retrieve or store custom user data.

Stand-alone Claiming Service (Used in CLI)

Claiming Service
  • Initiate the claiming process for devices.
  • Verify claiming requests for devices.

Cloud-to-Cloud Based Admin User Management

Cloud-to-Cloud
  • Create new users in the user email mobile user pool.
  • Delete users from the email mobile user pool.
  • Update passwords for users in the user email mobile user pool.

APIs for Superadmin Users​

Deployment Details
  • Retrieve deployment details.
Cognito App Client
  • Update configurations of Cognito app clients.
  • Retrieve details of all configured Cognito app clients.
Cognito Domain
  • Create, retrieve, or delete Cognito domains.
Third-Party Identity Providers
  • Configure, update, or retrieve identity providers.
Message Template
  • Update or retrieve message templates.
  • Retrieve lists of SES-verified email IDs.
Dashboard
  • Update dashboards to the latest versions.
  • Check available updates for dashboards.
Customer License
  • Upload customer licenses.
  • Retrieve details of uploaded customer license files.
  • Retrieve the current available license quota.
Node Registration

This is used by ESP RainMaker customers to generate bulk credentials for nodes.

  • Retrieve the MQTT hostname/IoT domain name.
  • Retrieve custom MQTT hostname/IoT domain name.
  • Generate required numbers of node IDs for users.
  • Retrieve statuses of generated node ID requests.
  • Retrieve certificate registration requests for which certificate registration is in progress.
  • Retrieve pre-signed URLs or statuses of node certificate registration requests.
  • Trigger registration of node certificates.
Superadmin User Management
  • Update the Superadmin of the RainMaker deployment.
Sender Email Update
  • Update the sender email of RainMaker deployment.
Common Custom Data
  • Add or update common custom data.
  • Retrieve common custom data.
Deployment Setting
  • Retrieve stored configuration details of services.
  • Backup, restore, or configure service configurations.
IoT Device Rate Limit Configuration
  • Configure or retrieve IoT device metrics limits.
API Requests Rate Limit Configuration
  • Update API requests rate limits.
  • Retrieve configured API requests rate limits.
Custom Mobile Platform Message Template
  • Create custom mobile platform message templates.
  • Retrieve or update configured custom mobile message templates.
Mobile Platform Application
  • Create or update new platform applications.
  • Retrieve lists of configured platform applications.
  • Remove configured platform applications.
Publish Message
  • Publish messages to users' devices.
External API Passthrough Service

External API Passthrough Service will be used by ESP RainMaker customers to call external APIs.

  • Retrieve, save, or update external API configurations.
Admin User Management
  • Create or update new users in the user email mobile user pool.
  • Retrieve details of users.
  • Delete user accounts.
Node Certificate CA
  • Upload node certificate CAs.
  • Retrieve all node certificate CAs.
Webhook Integration
  • Add new webhooks for specified integrations.
  • Update existing webhook configurations.
  • Retrieve webhook information.
  • Remove webhooks configured for integrations.
  • Retrieve webhook event mapping information.
  • Add webhook event mappings.
  • Remove webhook event mappings.
Statistical Service
  • Retrieve statistical information.
  • Initialize data for the stats service.
Mail Delivery Failure Logs
  • Retrieve logs of failures that occurred while sending emails.
API Gateway Stage
  • Upgrade RainMaker APIs.
Terms Policy
  • Update Terms of Use and Privacy Policy HTML files.
  • Retrieve Terms of Use and Privacy Policy file content and URLs.
  • Delete Terms of Use and Privacy Policy files.
Cloudwatch Log IAM User
  • Add or remove IAM users with read permissions for CloudWatch logs.
Log Level
  • Change log levels.
RainMaker Deployment Capabilities
  • Add or retrieve RainMaker capabilities.
API Statistics
  • Retrieve API statistics.
MQTT Statistics
  • Retrieve MQTT statistics.
Node Parameter Operations

Allows admins to control the state of devices.

  • Update or retrieve node parameters.

On this page