Skip to main content
API docs by Redocly

ESP RainMaker API Definitions for SuperAdmins (1.0.0)

Download OpenAPI specification:Download

E-mail: esp-rainmaker-admin@espressif.com License: Apache 2.0 Terms of Service

The API Defintions for the Rainmaker APIs, which are used by super admin users.

Find out more about ESP RainMaker

Get Deployment details api

API to fetch deployment details

Get the deployment details

This API is used to fetch the deployment details

Authorizations:
AccessToken
path Parameters
version
required
string
Default: "v1"

API Version (Current supported API Version is 'v1')

query Parameters
email_mobile_userpool
boolean
Default: false

If set to true, It fetches details of newer/Phone user pool

pre_requisite
boolean
Default: false

Responses

Response samples

Content type
application/json
Example
{
  • "base_url": "example_base_url",
  • "http_base_url": "example_base_url",
  • "region": "aws_region",
  • "account_id": "aws_account_id",
  • "build_info": "example_build_info",
  • "mqtt_endpoint": "example_mqtt_endpoint",
  • "user_pool_id": "example_user_pool_id",
  • "app_client_id": "example_app_client_id",
  • "OAuth_issuer": "OAuth issuer url",
  • "OAuth_url": "OAuth authorize url",
  • "OAuth_deployment": "true or false indicating OAuth deployment",
  • "super_admin_user_name": "email of superadmin user",
  • "dashboard_url": "RainMaker dashboard url"
}

Cognito App Client

Cognito App Client Operation

Updates configuration of Cognito app client

This API is used to configure Cognito app client.

Authorizations:
AccessToken
path Parameters
version
required
string
Default: "v1"

API Version (Current supported API Version is 'v1')

query Parameters
email_mobile_userpool
boolean

Points to userpool which supports mobile and email based authentication

Request Body schema: application/json

The required parameter client_id is the unique id given to user pool client. You can get the client_id from Rainmaker Dashboard.On Rainmaker Dashboard, go to Deployment settings, select Cognito Configuration tab. In Cognito App Client Configurations section, you can get the client_id of all configured user pool clients.
Either providers or callback_urls must be provided in request body.
Providers field is the list of Identity Providers that you want to configure. callback URL indicates where the user is to be redirected after a successful sign-in. If providers or callback_urls is not specified, it will be updated as blank.

client_id
required
string
providers
Array of strings
callback_urls
Array of strings

Responses

Request samples

Content type
application/json
{
  • "client_id": "client_id",
  • "providers": [
    ],
  • "callback_urls": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "description": "Success description"
}

Gives details of all configured Cognito app clients

This API lists configured Cognito app clients and gives details of each app client

Authorizations:
AccessToken
path Parameters
version
required
string
Default: "v1"

API Version (Current supported API Version is 'v1')

query Parameters
email_mobile_userpool
boolean

Points to userpool which supports mobile and email based authentication

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Cognito Domain

Cognito Domain Operation

Creates Cognito domain

This API is used to create Cognito domain name. The domain name is domain that hosts the sign-up and sign-in pages for your application.

Authorizations:
AccessToken
path Parameters
version
required
string
Default: "v1"

API Version (Current supported API Version is 'v1')

query Parameters
email_mobile_userpool
boolean

Points to userpool which supports mobile and email based authentication

Request Body schema: application/json
domain_name
string

Responses

Request samples

Content type
application/json
{
  • "domain_name": "domain-name"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "description": "Success description"
}

Fetches Cognito domain

This API is used to get Cognito domain name

Authorizations:
AccessToken
path Parameters
version
required
string
Default: "v1"

API Version (Current supported API Version is 'v1')

query Parameters
email_mobile_userpool
boolean

Points to userpool which supports mobile and email based authentication

Responses

Response samples

Content type
application/json
{
  • "domain_name": "domain-name"
}

Deletes Cognito domain

This API deletes the cognito domain configured in user account

Authorizations:
AccessToken
path Parameters
version
required
string
Default: "v1"

API Version (Current supported API Version is 'v1')

query Parameters
email_mobile_userpool
boolean

Points to userpool which supports mobile and email based authentication

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "description": "Success description"
}

Identity Providers

Configure third party Identity Providers for User Authentication

Configures Identity Providers

This API configures Identity Providers for user authentication.

Authorizations:
AccessToken
path Parameters
version
required
string
Default: "v1"

API Version (Current supported API Version is 'v1')

query Parameters
email_mobile_userpool
boolean

Points to userpool which supports mobile and email based authentication

Request Body schema: application/json
required

Provider Type is required parameter. ClientId, KeyId, TeamId and PrivateKey are required for configuration of SignInWithApple. Client Id and Client Secret are required for configuring Goolge and GitHub identity providers.

One of
provider_type
required
string
team_id
required
string
key_id
required
string
private_key
required
string
client_id
required
string

Responses

Request samples

Content type
application/json
Example
{
  • "provider_type": "SignInWithApple",
  • "team_id": "team_id",
  • "key_id": "key_id",
  • "private_key": "private_key",
  • "client_id": "client_id"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "description": "Success description"
}

Updates Identity Providers

This API is used to update Identity Providers for user authentication

Authorizations:
AccessToken
path Parameters
version
required
string
Default: "v1"

API Version (Current supported API Version is 'v1')

query Parameters
email_mobile_userpool
boolean

Points to userpool which supports mobile and email based authentication

Request Body schema: application/json
required

Provider Type is required parameter. ClientId, KeyId, TeamId and PrivateKey are required for configuration of SignInWithApple.Client Id and Client Secret are required for configuring Goolge and GitHub identity providers.Provider name is optional parameter.

One of
provider_type
required
string
team_id
required
string
key_id
required
string
private_key
required
string
client_id
required
string

Responses

Request samples

Content type
application/json
Example
{
  • "provider_type": "SignInWithApple",
  • "team_id": "team_id",
  • "key_id": "key_id",
  • "private_key": "private_key",
  • "client_id": "client_id"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "description": "Success description"
}

Fetches Configured Identity Providers

This API is used to get all configured Identity Providers

Authorizations:
AccessToken
path Parameters
version
required
string
Default: "v1"

API Version (Current supported API Version is 'v1')

query Parameters
email_mobile_userpool
boolean

Points to userpool which supports mobile and email based authentication

Responses

Response samples

Content type
application/json
Example
null

Message Template

Email Message Customization

Updates Message Template

This API is used to customize Email messages sent to users. For example, to customize Email message which has verification code for user verification, template type is INVITE_MESSAGE.

Authorizations:
AccessToken
path Parameters
version
required
string
Default: "v1"

API Version (Current supported API Version is 'v1')

query Parameters
email_mobile_userpool
boolean

If set to true, It fetches details of newer/Phone user pool

Request Body schema: application/json
required

For EMAIL templates Message Type, Message Subject, Message Text, Template Type are required parameters. If from Email Address is not specified for INVITE_MESSAGE, invitation mail is sent from AWS Cognito Service.
For SMS templates Message Type, Message Text, Template Type are required parameters. If the sender id is not specified, default sender id from cognito is used.
Valid template types are INVITE_MESSAGE, WELCOME_MESSAGE_ADMIN, DELETE_USER_REQUEST_MESSAGE,FORGOT_PASSWORD_MESSAGE, DELETE_USER_CONFIRM_MESSAGE, TAGS_ASSIGNMENT_VERIFICATION_MESSAGE and SMS_DELETE_USER_REQUEST_MESSAGE
Message Text must have {####} placeholder for verification code.
Message Text must have {{enter_email}} placeholder for User email.
Message Text can optionally have {{assigned_tags}} placeholder for adding the assigned tags to the email for TAGS_ASSIGNMENT_VERIFICATION_MESSAGE template type only.

One of
message_subject
required
string

Email Message Subject

message_text
required
string

Email Message Text
Message Text must have {####} placeholder for verification code.
Message Text must have {{enter_email}} placeholder for User email.

template_type
required
string
Enum: "INVITE_MESSAGE" "WELCOME_MESSAGE_ADMIN" "WELCOME_MESSAGE_USER" "DELETE_USER_REQUEST_MESSAGE" "FORGOT_PASSWORD_MESSAGE" "SMS_DELETE_USER_REQUEST_MESSAGE"

Message template type

from_email_address
string

User Email Address
The user email address must be SES verified email

from_user_name
string

User Name

Responses

Request samples

Content type
application/json
Example
{
  • "message_subject": "Email Message Subject",
  • "message_text": "Email Message Text",
  • "template_type": "INVITE_MESSAGE",
  • "from_email_address": "User Email Address",
  • "from_user_name": "User Name"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "description": "Success description"
}

Fetches Message Templates

This API is used to get list of stored Message Templates. Message templates are the templates used for email messages sent to users.

Authorizations:
AccessToken
path Parameters
version
required
string
Default: "v1"

API Version (Current supported API Version is 'v1')

query Parameters
template_type
string
Enum: "INVITE_MESSAGE" "WELCOME_MESSAGE_ADMIN" "WELCOME_MESSAGE_USER" "DELETE_USER_REQUEST_MESSAGE" "FORGOT_PASSWORD_MESSAGE" "SMS_DELETE_USER_REQUEST_MESSAGE"

Template Type

Responses

Response samples

Content type
application/json
Example
[
  • {
    }
]

Fetches list of SES verified Email IDs

This API is used to get list of SES Verified Email IDs in AWS account

Authorizations:
AccessToken
path Parameters
version
required
string
Default: "v1"

API Version (Current supported API Version is 'v1')

Responses

Response samples

Content type
application/json
{
  • "verified_email": [
    ]
}

Dashboard

Update Dashboard

Updates dashboard to latest version

This API is used to update Rainmaker dashboard to the latest version.

Authorizations:
AccessToken
path Parameters
version
required
string
Default: "v1"

API Version (Current supported API Version is 'v1')

Request Body schema: application/json

'version' is required parameter.

version
string

Responses

Request samples

Content type
application/json
{
  • "version": "current_dashboard_version"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "description": "Success description"
}

Check available updates for dashboard

This API is used to check updates for dashboard

Authorizations:
AccessToken
path Parameters
version
required
string
Default: "v1"

API Version (Current supported API Version is 'v1')

query Parameters
current_version
required
string

Responses

Response samples

Content type
application/json
{
  • "version": "latest_version"
}

Customer License

License APIs for customer super admin

API for the super admin user to upload customer license

This API is used by customer's super admin users to upload license file to their Rainmaker environment.

Authorizations:
AccessToken
path Parameters
version
required
string
Default: "v1"

API Version (Current supported API Version is 'v1')

Request Body schema: application/json

Request body for uploading base64 license file content to customer's Rainmaker environment

file_content_b64
string

Responses

Request samples

Content type
application/json
{
  • "file_content_b64": "file_content_b64"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "description": "Success description"
}

API for the super admin user to get uploaded customer license file details

This API is used by customer's super admin users to get customer license file details which are uploaded in the Customer's Rainmaker account.

Authorizations:
AccessToken
path Parameters
version
required
string
Default: "v1"

API Version (Current supported API Version is 'v1')

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "license_files": [
    ]
}

API for the super admin user to get the current available license quota

This API is used by customer's super admin users to get the current available license quota.

Authorizations:
AccessToken
path Parameters
version
required
string
Default: "v1"

API Version (Current supported API Version is 'v1')

Responses

Response samples

Content type
application/json
Example
{
  • "license_quota": "1000000",
  • "available_quota": 899749,
  • "used_quota": 100251
}

Node Registration

Node Registration service will be used by the ESP Rainmaker customers to generate the bulk credentials for the nodes.

Get the MQTT Hostname/IoT Domain name

This API returns the MQTT domain hostname.

Authorizations:
AccessToken

Responses

Response samples

Content type
application/json
{
  • "mqtt_host": "string"
}

Get the Custom MQTT Hostname/IoT Domain name

This API returns the custom MQTT domain hostname.

Authorizations:
AccessToken

Responses

Response samples

Content type
application/json
{
  • "mqtt_host": "string"
}

Generates required number of node_ids for the user

This API sends a request to generate the required number of node_ids. If the user doesn’t have sufficient quota, an error will be returned, else a request_id will be returned.

Authorizations:
AccessToken
Request Body schema: application/json
required

Request body to generate node_ids for user

node_count
number

Responses

Request samples

Content type
application/json
{
  • "node_count": 0
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "request_id": "string"
}

Get the status of generate node_ids request

This API is used to query the status of the generate node_ids request. This API takes request_id as query parameter and returns response containing status of the request and a url for the file containing the node_ids if status is success

Authorizations:
AccessToken
query Parameters
request_id
required
string

RequestId for generating the required number of node_ids

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "url": "string"
}

Get certificate registration requests, for which certificate registration is in progress.

This API is to get the certificate files

  • This API is used to fetch list of last 10 requests made that are in_progress when no query parameter is passed
  • If the file_name and request_id is specified certificate file pre-signed download URL is returned (Validity 1hr).
  • If the file_list is set to true then list of certificate files that were uploaded will be sent.
  • We will send the file path after the constant path which is /users//node_certificates/. To support pagination num_records and start_id are present

Authorizations:
AccessToken
query Parameters
file_name
string

Optional. Name of the file, for which pre-signed download URL is to be fetched.

file_list
boolean
Default: false

Optional flag (true/false), to indicate if the list of uploaded certificate files need to be returned. Default (false)

num_records
string

Optional. Sets the maximum number of keys returned in the response. Default 10

start_id
string

Optional. Used for pagination.

Responses

Response samples

Content type
application/json
Example
[
  • {
    }
]

Get Pre-signed url or status of the node certificate registration request

This API is used to fetch presigned url or status of the node certificate registration request.

  • The user needs to specify either request_id or the file_name.
  • If the request_id is specified then the status of the request is returned.
  • If the file_name is specified then the pre-signed upload URL is returned.

    • Authorizations:
    AccessToken
    query Parameters
    file_name
    string

    Name of the file, for which upload pre-signed URL is to be fetched.

    request_id
    string

    request_id of the existing request to upload/register certificate

    Responses

    Response samples

    Content type
    application/json
    Example
    {
    • "url": "pre_signed_url_of_file",
    • "status": "success"
    }

    Triggers the registration of node certificates.

    After the user uploads the .csv file containing the node certificates to s3 bucket this api will be called. It is expected that the user will upload the file containing node certificates separately using CLI/other tool. This API triggers the registration of node certificates and returns the RequestId.

    Filename, file MD5 and request ID(which will be provided in the GET {{url}}/v1/admin/node_certificates/register?file_name=node_certs.csv) are required request parameters while Type, Model, group_name , parent_group_id, subtype, tags, force, update_nodes and refresh_token are optional request parameters.

    Tags should be provided in the form of comma separated node tags e.g: tag1:value1,tag2:value2

    When group name is provided then nodes registered will be added to the given group.

    If group name is not provided then nodes are added to a new node group, the group name would be as below:

  • If no type, model, group name provided, then group name will be Nodes-13Jan2022-16:38
  • If only type is provided (Eg. Lightbulb), then group name will be Lightbulb-13Jan2022-16:38
  • If only model is provided (Eg. led_light), then group name will be led_light-13Jan2022-16:38
  • If both, type and model are provided as above, then group name will be Lightbulb_led_light-13Jan2022-16:38
  • force: This argument will decide whether to ignore(force=True) or return the error (force=False) for duplicate node registration. also updates the existing certificates
  • update_nodes: This argument will decide whether to skip the license check and registration of the device certificates, and only update the nodes table with type, model, subtype, and tags.
  • update_nodes and --force: If both are given, only the existing nodes will be updated with the new type, model, subtype and tags, Also the certificates will be updated.New nodes will be skipped.


    Either parent groupname or parent groupID can be provided.If both are provided, parent groupid will get precedence.


    If the refresh token is not provided then the nodes would not be added to the group.

    • Authorizations:
    AccessToken
    Request Body schema: application/json
    required

    Request body to upload certificate files

    file_name
    string
    file_md5
    string
    request_id
    string
    type
    string
    model
    string
    group_name
    string
    refresh_token
    string
    parent_group_name
    string
    parent_group_id
    string
    subtype
    string
    tags
    string
    force
    boolean
    update_nodes
    boolean

    Responses

    Request samples

    Content type
    application/json
    {
    • "file_name": "file_name",
    • "file_md5": "file_md5",
    • "request_id": "job_request_id",
    • "type": "device_type",
    • "model": "device_model",
    • "group_name": "Node_light",
    • "refresh_token": "string",
    • "parent_group_name": "parent_group_name",
    • "parent_group_id": "parent_group_id",
    • "subtype": "subtype",
    • "tags": "tag1:value1,tag2:value2",
    • "force": true,
    • "update_nodes": true
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "file_name": "node_certs.csv",
    • "file_md5": "18116d4ae069ab2c3e8407b526df4924",
    • "request_id": "<job_request_id>",
    • "type": "LightBulb",
    • "model": "LED1.1",
    • "group_name": "test_group",
    • "refresh_token": "<refresh_token>",
    • "parent_group_id": "<parent_group_id>",
    • "parent_group_name": "<parent_group_name>",
    • "subtype": "bulb",
    • "tags": "tag1:value1,tag2:value2",
    • "force": true,
    • "update_nodes": true
    }

    Super Admin User Management

    Super Admin User Management

    Updates the super admin of rainmaker deployment

    This API updates the super admin of rainmaker deployment. This API assumes that the new super admin user doesn't exist in this RainMaker deployment.

    Note: When the super admin is changed, please send an update about the same to esp-rainmaker-support@espressif.com to ease the management of RainMaker.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    Request Body schema: application/json
    required

    Request body for updating super admin username

    One of
    new_super_admin
    required
    string

    New Super Admin's Valid email address
    The new Super Admin user should not exist in deployment
    Request is valid for 5 mins

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "new_super_admin": "user@domain.com"
    }

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "description": "Success description"
    }

    Sender Email Update

    Sender Email Update

    Updates the sender email of rainmaker deployment

    This API updates the sender email of rainmaker deployment.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    Request Body schema: application/json
    required

    Request body for updating sender email

    One of
    new_sender_email
    required
    string

    New sender email address
    The new email should be SES verified email in the account
    Request is valid for 5 mins

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "new_sender_mail": "example@domain.com"
    }

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "description": "Success description"
    }

    Common Custom Data

    Adds or Updates the common custom data

    This API Adds or Updates the common custom data.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    Request Body schema: application/json
    required

    Request body for adding or updating common custom data. This will be a JSON payload. The maximum storage allowed for each name is 300KB(after payload is trimmed of space and newline characters). It will have fields: name and value. The name should be a string and value can be any of: JSON, string, int, boolean, array of Json objects.When data is an array of objects, user should specify the entire object for modifying the data.When data is json object, user can perform operations similar to user custom data.The common custom data can be empty or it can have some data as shown below:
    {
        "name": "faults",
        "value": [
            {
                "device_type": "ac",
                "country": "India",
                "error_codes": [
                    {
                        "code": "E1",
                        "description": "Error E1 Description",
                        "additional_field": "AdditionalFieldValue1"
                    },
                    {
                        "code": "E2",
                        "description": "Error E2 Description",
                        "additional_field": "AdditionalFieldValue2"
                    }
                ]
            },
            {
                "device_type": "refrigerator",
                "country": "Australia",
                "error_codes": [
                    {
                        "code": "P1",
                        "description": "Error P1 Description",
                        "additional_field": "AdditionalFieldValue1"
                    },
                    {
                        "code": "P2",
                        "description": "Error P2 Description",
                        "additional_field": "AdditionalFieldValue2"
                    }
                ]
            }
        ]
    }

    name
    string
    Array of objects

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "name": "ac_faults",
    • "value": {
      },
    • "perms": [
      ]
    }

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "description": "Success description"
    }

    Fetches the common custom data

    This API fetches common custom data

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    name
    string

    Name of common custom data to be fetched

    Responses

    Response samples

    Content type
    application/json
    Example
    [
    • {
      },
    • {
      }
    ]

    Deployment Setting

    Deployment settings api

    API for the super admin user to get service's stored configuration details.

    This API is used by customer's super admin users to get service's stored configuration details. Can be used to get configurations for building mobile apps.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    service
    required
    string
    Enum: "cognito_appclient" "rbac" "encryption" "user_archival" "node_apis" "custom_user_context" "location_trigger" "mobile_app" "OAuth_only" "custom_sms"

    Service whose configuration is to be fetched.

    query Parameters
    platform
    string
    Enum: "ios" "android"

    If service is mobile_app then platform is required

    package_name
    string
    Example: package_name=com.package.name

    If service is mobile_app, package name of the Application is Mandatory

    isEmailUserPool
    string
    Default: false

    If service is mobile_app, use true for older/email-only userPool or false for newer/email-and-phone userPool. Default is Newer userpool.

    Responses

    Response samples

    Content type
    application/json
    Example
    {
    • "user_poolid": "user_poolid",
    • "client_id": "client_id",
    • "client_name": "client_name",
    • "identity_providers": [
      ],
    • "callback_urls": [
      ]
    }

    API for the super admin user to backup service's configuration

    This API is used by customer's super admin users to backup service's configuration.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    service
    required
    string
    Value: "cognito_appclient"

    Service

    Responses

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "description": "Success description"
    }

    API for the super admin user to restore service's configuration

    This API is used by customer's super admin users to restore service's configuration.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    service
    required
    string
    Value: "cognito_appclient"

    Service

    Responses

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "description": "Success description"
    }

    API for the super admin user to configure service's configuration

    This API is used by customer's super admin users to configure service's configuration.

    RBAC: API level fine grained access for admins. Can create policies, roles and assign to specific admins.

    Node APIs: Nodes can use HTTP instead of MQTT to communicate with Cloud. Currently, supports just OTA operations.

    Encryption: Encrypts sensitive fields of Users like email, phone number, username, etc. Cannot be disable once enabled

    Role-based Access Control: Use RBAC(Role-based Access Control) to enable fine-grained access evaluation for users. If RBAC is disabled, flag-based approach is used to check user access to operations, as opposed to user roles and policies approach used by RBAC. RBAC can be enabled/disabled with this API.

    User Archival: Enables the archival service which warns year old inactive users that their data might be deleted. Deletes that User after 3 months of cooldown.

    Custom user context: custom_auth_userid will be able carry out user operations on behalf of others by providing user identifier in the 'Custom-UserId' header

    OAuth only (Beta): Use OAuth for identity management instead of Cognito. Currently, only third party logins supported. This is strictly to be enabled before phone apps are live. Please consult the RainMaker support team for more details.

    Command Response History: Enables/disables the command response history.

    Node Data Access: Enables/disables "read" or "write" access to node data like params and config.

    Custom SMS: Sets the Sender ID, Entity ID, Template ID and Country to send Custom SMS to users via registered Sender ID. Country code from the phone number is used to get details of the country while sending SMS.

    Location Triggers: The default polling interval is 30 minutes. The default host url is 'https://api.openweathermap.org/data/2.5/weather?units=metric' with default units as 'metric'. The supported units are 'standard', 'metric', 'imperial'. List of all parameters and supported units:

    Parameter
    		 Description
    		 Standard
    		 Metric
    		 Imperial
    o temperature Temperature Kelvin Celsius Fahrenheit
    o pressure Atmospheric Pressure hPa hPa hPa
    o humidity Humidity % % %
    o wind_speed Wind Speed meter/sec meter/sec miles/hour
    o weather_condition Weather Condition check note check note check note

    Note: The supported weather conditions are 'Thunderstorm', 'Drizzle', 'Rain', 'Snow', 'Clear', 'Clouds', 'Mist', 'Smoke', 'Haze', 'Dust', 'Fog', 'Sand', 'Ash', 'Squall', 'Tornado'

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    service
    required
    string
    Enum: "rbac" "node_apis" "custom_user_context" "location_trigger" "encryption" "user_archival" "OAuth_only" "cmd_resp_history" "custom_sms" "node_data_access"

    Service to configure.

    Request Body schema: application/json

    Request body for configuring a Service

    One of
    rbac_enabled
    boolean

    Indicates whether Role Based Access Control is to be enabled or not
    If enabled, the user's role is examined to determine their permission to access the API, rather than relying on user flags

    allow_same_role_level
    boolean

    Determines if two users with the same role level value can be assigned a role to each other.
    By default, it is set to false. A user can only add roles that have lower role level values than the highest role level of the current user.

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "rbac_enabled": true
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "status": "success",
    • "description": "Successfully configured"
    }

    IoT Device Rate Limit Configuration

    API to configure allowed limits for IoT device metrics

    Configure IoT Device metrics limit

    This API is used to configure various limits in IoT devices security metrics. The supported metrics are:
    1.Number of authrorization failures
    2.Number of connection attempts
    3.Number of Messages sent.
    All the metrics count are measured in 5 minutes time period. If the device metrics value is higher than the maximum allowed values, alarm is triggered and mail is sent to configured email ID

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    Request Body schema: application/json
    required

    num_messages_sent, num_authorization_failures, num_connection_attempts are the values that can be specified in the request body.

    num_messages_sent
    number >= 1

    Number of messages sent by a device to IoT core

    num_authorization_failures
    number >= 1

    Number of times a device's request is declined by IoT Core. For E.g It publishes to a topic it is not authorized to

    num_connection_attempts
    number >= 1

    Number of times a device connects to IoT core (both successful and failed connections)

    Responses

    Request samples

    Content type
    application/json
    {
    • "num_messages_sent": 100,
    • "num_authorization_failures": 1,
    • "num_connection_attempts": 25
    }

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "description": "Success description"
    }

    Get IoT Device metrics limit

    This API is used to get the value of configured limits in IoT devices security metrics. the value indicates the number of allowed operations in 5 minutes period.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    Responses

    Response samples

    Content type
    application/json
    {
    • "num_messages_sent": 100,
    • "num_authorization_failures": 1,
    • "num_connection_attempts": 25
    }

    API Requests Rate Limit Configuration

    APIs to fetch or update rate limit for API requests

    Update API requests rate limit

    This API is used to update the API requests rate limit for RainMaker APIs.
    The rate limit is the maximum number of requests from a single IP address that are allowed in a five-minutes period. Requests will be blocked once this limit is reached. The requests from an IP address are automatically unblocked after the request rate falls below the limit.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    Request Body schema: application/json
    rate_limit
    integer

    Responses

    Request samples

    Content type
    application/json
    {
    • "rate_limit": 1000
    }

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "description": "Success description"
    }

    Fetches the configured API requests rate limit

    This API is used to get the API requests rate limit, i.e, the threshold count of API requests per 5 minutes period, after which API requests will be blocked.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    Responses

    Response samples

    Content type
    application/json
    {
    • "rate_limit": 1000
    }

    Custom Mobile Platform Message Template

    Custom Mobile Platform Message Template

    Create custom mobile platform message template

    This API will be used to create custom mobile platform message template.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    Request Body schema: application/json
    required

    Request body for creating custom mobile message template.The message title can have a maximum of 50 characters and message body can have maximum of 1500 characters.

         Event Data : When event data is enabled, Event's raw data is shared with mobile.

         Event Type : Event topic name.[same as SNS topic name]

    Custom messages for the events which are enabled for mobile push notifications should have number of '%s' depending on the event types. Default events should have '%s' which will get substituted by device ID.Specific event types will be mentioned in the below list.

    Supported event topics:

  • esp_rainmaker_sns_user_node_added
  • esp_rainmaker_sns_user_node_removed   (number of %s should be 3 which will get substituted by primary user name, request ID and Nodes)
  • esp_rainmaker_sns_node_registration
  • esp_rainmaker_sns_node_parameter_modified (number of %s should be 2 which will get substituted by Node ID and param change Payload)
  • esp_rainmaker_sns_node_status_modified
  • esp_rainmaker_sns_node_firmware_updated
  • esp_rainmaker_sns_user_node_sharing_add   (number of %s should be 3 which will get substituted by primary user name, request ID and Nodes)
  • esp_rainmaker_sns_node_connected
  • esp_rainmaker_sns_node_disconnected
  • esp_rainmaker_sns_node_registered
  • esp_rainmaker_sns_node_status_modified
  • esp_rainmaker_sns_admin_user_added
  • esp_rainmaker_sns_new_tags_added
  • esp_rainmaker_sns_existing_tags_attached
  • esp_rainmaker_sns_automation_triggered  (single %s will be replaced by Automation name )
  • esp_rainmaker_sns_user_node_group_sharing_add  (number of %s should be 2 which will get substituted by shared_from user name and group name)
  • esp_rainmaker_sns_user_node_group_sharing_add_declined  (number of '%s' should be 3 which will get substituted by Shared_to username, sharing request ID and groupname)
  • esp_rainmaker_sns_user_node_group_sharing_add_accepted  (number of '%s' should be 3 which will get substituted by Shared_to username, sharing request ID and groupname)
  • esp_rainmaker_sns_user_node_group_added (single %s will be replaced by group name)
  • esp_rainmaker_sns_user_node_group_removed (single %s will be replaced by group name)
  • esp_rainmaker_sns_node_config_modified

    • event_type
    string

    RainMaker Event type

    message_body
    string <= 1500 characters

    Custom message body

    event_data
    string
    Enum: "enable" "disable"

    Indicates whether to enable or disable event data

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "event_type": "<esp_rainmaker_sns_node_disconnected>",
    • "message_title": "<message title>",
    • "message_body": "<message body>",
    • "event_data": "<enable/disable>"
    }

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "description": "Success description"
    }

    This API fetches configured custom mobile message template

    This API fetches configured custom mobile message template.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    event_type
    string

    event type

    Responses

    Response samples

    Content type
    application/json
    {
    • "common_custom_title": "Esp Rainmaker",
    • "custom_message_templates": [
      ]
    }

    This API updates the configured custom mobile message template.

    This API updates the configured custom mobile message template.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    event_type
    string

    event type (Updating message title, doesn't require event_type)

    Request Body schema: application/json
    required

    Request body for updating custom mobile mesage template.The message title can have a maximum of 50 characters and message body can have maximum of 1500 characters.

    event_type
    string

    RainMaker Event type

    message_body
    string <= 1500 characters

    Custom message body

    event_data
    string
    Enum: "enable" "disable"

    Indicates whether to enable or disable event data

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "message_body": "<message body>",
    • "event_data": "<enable/disable>"
    }

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "description": "Success description"
    }

    Mobile Platform Application

    Manage platform application

    Creates the new platform application

    This API creates a new mobile platform application

         Platform : Represents a push notification service from a provider like Google, Amazon or Microsoft.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    Request Body schema: application/json
    required

    Request body for creating new platform application, Valid platform to be specified are ADM,APNS,APNS_SANDBOX or GCM.

    One of
    platform
    required
    string

    Specify GCM as platform for Android that your app is registered with.

    name
    string [ 2 .. 256 ] characters ^[a-zA-Z0-9_.-]+$

    Unique name of the platform

    api_key
    required
    string

    Provide Google API Key

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "platform": "GCM",
    • "name": "name",
    • "api_key": "<server api key>"
    }

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "platform_application_arn": "platform application arn"
    }

    Updates the platform application

    This API updates mobile platform application

         Platform : Represents a push notification service from a provider like Google, Amazon or Microsoft.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    Request Body schema: application/json
    required

    Request body for updating new platform application, Valid platform to be specified are ADM,APNS,APNS_SANDBOX or GCM.

    One of
    platform
    required
    string

    Specify GCM as platform for Android that your app is registered with.

    name
    string [ 2 .. 256 ] characters ^[a-zA-Z0-9_.-]+$

    Unique name of the platform

    api_key
    required
    string

    Provide Google API Key

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "platform": "GCM",
    • "name": "name",
    • "api_key": "<server api key>"
    }

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "platform_application_arn": "platform application arn"
    }

    This API fetches the list of configured platform applications

    This API fetches configured platform application

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    Responses

    Response samples

    Content type
    application/json
    {
    • "platform_applications": [
      ]
    }

    This API removes the configured platform application.

    This API removes the configured platform application.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    platform_application_arn
    required
    string

    platform application arn

    Responses

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "description": "Success description"
    }

    Publish Message

    Publish Message

    Publish message to user's device

    This API will be used to publish messages to user's device in a bulk of 100000 users.

    If the users wants to publish the message to specific users, at least one of email or user_id list needs to be provided. user_id has more preference over email.

    If the users wants to publish to all non-internal users then only the publish_to_all_users should be set to true, without any fields - email and user_id

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    Request Body schema: application/json
    required

    Request body for publish message.The message title can have a maximum of 50 characters and message body can have maximum of 1500 characters. The message type and additonal_info are optional parameters. The message type can have a maximum of 25 characters and the additional info can have a total of 1400 characters with each key not excedding 50 characters and each value not excedding 150 characters.

    One of
    message_title
    string <= 50 characters

    Message title

    message_body
    string <= 1500 characters

    Message body

    email
    string

    user email addresses separated by commas
    Maximum 100000 user emails can be specified

    user_id
    string

    userId separated by commas
    Maximum 100000 userIds can be specified

    type
    string <= 25 characters

    Type of message

    additional_info
    object <= 1400 characters

    Additional Info
    key length limit is 50 and attribute length limit is 150

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "message_title": "<message title>",
    • "message_body": "<message body>",
    • "email": "email_id1@domain.com,email_id1@domain.com",
    • "user_id": "user_id1,user_id2",
    • "type": "ADVERTISEMENT",
    • "additional_info": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "description": "Success description"
    }

    External API Pass Through Service

    External API Pass Through Service will be used by the ESP Rainmaker customers to call external APIs.

    Fetches external API configurations

    This API is used to fetch configurations of external API. To retrieve a specific service, provide a service ID or to obtain a list, provide the starting characters of the service name.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    service_id
    string

    This parameter is used to specify the service id.

    service_name
    string

    This parameter is used to fetch service list based on starting of service name

    start_id
    string

    This parameter is used for pagination.

    num_records
    string
    Default: 30

    This parameter is used to specify number of records. Max Value = 30

    Responses

    Response samples

    Content type
    application/json
    {
    • "next_id": "string",
    • "api_config_list": [
      ]
    }

    Saves external API configurations

    This API is used to save new configurations for external APIs. It will return a unique ID generated by Rainmaker for each external service, called service_id. This service_id is used to call the GET /passthrough API.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    Request Body schema: application/json
    required
    service_name
    required
    string

    This field is used to specify the service name.Service name should be unique.

    api_url
    required
    string

    This field is used to specify the api endpoint url of external api.

    storage_type
    string

    This field is used to specify the storage type. All other configurations are stored in DynamoDB, while sensitive information such as auth token or API key is saved according to the specified storage type. Currently, DynamoDB is the only supported storage type.

    auth_type
    required
    string

    This field is used to specify the authorization behaviour of external API.
    Possible Values-
    1. api_key:- This refers to a static API key that is used for authorization of the external API. It is a fixed and provided by the API provider, which remains constant for each request.
    2. static_auth_token:- This refers to a static auth token that is used for authorization of the external API. It is typically provided by the API provider and remains unchanged for each request.
    3. rotating_auth_token:- This type of authorization involves generating an authentication token by calling a login API. Unlike static tokens, rotating tokens are dynamically generated, often with a limited lifespan.
    4. none:- This indicates that no authorization is required for accessing the API.

    api_key
    string

    Static api key used for authorization of external api. Provide this field only if the auth_type is api_key.

    auth_token
    string

    Static auth token used for authorization of external api. Provide this field only if the auth_type is static_auth_token.

    auth_send_medium
    string

    The medium through which the external API accepts authorization information.
    Possible Values-
    1. query_param:- This specifies that external api expect auth parameter(api key or auth token) in query params.
    2. http_header:- This specifies that external api expect auth parameter(api key or auth token) in http header.
    Default values-
    1. The default value for the 'api_key' auth type is 'query_param'.
    2. The default value for the 'static_auth_token' and 'rotating_auth_token' auth types is 'http_header'.

    auth_field_name
    string

    The name of the field when sending authorization information.For Ex While sending an auth token through the HTTP header, the auth_field_name could be 'Authorization' or 'authorization'.
    Default values-
    1. For 'query_param' auth send medium default value is 'api_key'.
    2. For 'http_header' auth send medium default value is 'Authorization'.

    login_api_url
    string

    This field is used to specify the api endpoint url of login api.

    login_api_request_type
    string
    Default: "POST"

    This field is used to specify the Http request type of login API.

    login_cred_send_medium
    string
    Default: "body"

    The medium through which the login API accepts credentials.
    Possible Values-
    1. query_param:- This specifies that login api expect credentials in query params.
    2. http_header:- This specifies that login api expect credentials in http header.
    3. body:- This specifies that login api expect credentials in request body.

    login_credentials
    string

    Key and value pair of credentials in Json string format.

    login_cred_validation_time
    string

    Authentication token validity duration, measured in seconds.

    auth_field_name_in_resp
    string

    The field name that contains the authentication token in the login API response. For example, if the login API response looks like this {"auth_token":"XXX"}, then the auth_field_name_in_resp is 'auth_token'.

    auth_prefix
    string

    Prefix to be attached to the authentication token received from the login API before sending it through another API.

    Responses

    Request samples

    Content type
    application/json
    {
    • "service_name": "OpenWeather",
    • "api_url": "https://api.example.com",
    • "storage_type": "dynamodb",
    • "auth_type": "api_key",
    • "api_key": null,
    • "auth_token": null,
    • "auth_send_medium": "query_param",
    • "auth_field_name": "Authorization",
    • "login_api_url": "https://api.example.com/login",
    • "login_api_request_type": "POST",
    • "login_cred_send_medium": "body",
    • "login_credentials": "{\"user_name\":\"abc@gmail.com\",\"password\":\"1234\"}",
    • "login_cred_validation_time": 1800,
    • "auth_field_name_in_resp": "authtoken",
    • "auth_prefix": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "service_id": "string",
    • "service_name": "string",
    • "status": "string"
    }

    Updates external API configurations

    This API is used to update configurations for external APIs.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    service_id
    string

    This parameter is used to specify the service id.

    Request Body schema: application/json
    required
    service_name
    string

    This field is used to specify the service name.Service name should be unique.

    api_url
    string

    This field is used to specify the api endpoint url of external api.

    auth_type
    string

    This field is used to specify the authorization behaviour of external API.
    Possible Values-
    1. api_key:- This refers to a static API key that is used for authorization of the external API. It is a fixed and provided by the API provider, which remains constant for each request.
    2. static_auth_token:- This refers to a static auth token that is used for authorization of the external API. It is typically provided by the API provider and remains unchanged for each request.
    3. rotating_auth_token:- This type of authorization involves generating an authentication token by calling a login API. Unlike static tokens, rotating tokens are dynamically generated, often with a limited lifespan.
    4. none:- This indicates that no authorization is required for accessing the API.

    api_key
    string

    Static api key used for authorization of external api. Provide this field only if the auth_type is api_key.

    auth_token
    string

    Static auth token used for authorization of external api. Provide this field only if the auth_type is static_auth_token.

    auth_send_medium
    string

    The medium through which the external API accepts authorization information.
    Possible Values-
    1. query_param:- This specifies that external api expect auth parameter(api key or auth token) in query params.
    2. http_header:- This specifies that external api expect auth parameter(api key or auth token) in http header.

    auth_field_name
    string

    The name of the field when sending authorization information.For Ex While sending an auth token through the HTTP header, the auth_field_name could be 'Authorization' or 'authorization'.

    login_api_url
    string

    This field is used to specify the api endpoint url of login api.

    login_api_request_type
    string
    Default: "POST"

    This field is used to specify the Http request type of login API.

    login_cred_send_medium
    string
    Default: "body"

    The medium through which the login API accepts credentials.
    Possible Values-
    1. query_param:- This specifies that login api expect credentials in query params.
    2. http_header:- This specifies that login api expect credentials in http header.
    3. body:- This specifies that login api expect credentials in request body.

    login_credentials
    string

    Key and value pair of credentials in Json string format.

    login_cred_validation_time
    string

    Authentication token validity duration, measured in seconds.

    auth_field_name_in_resp
    string

    The field name that contains the authentication token in the login API response. For example, if the login API response looks like this {"auth_token":"XXX"}, then the auth_field_name_in_resp is 'auth_token'.

    auth_prefix
    string

    Prefix to be attached to the authentication token received from the login API before sending it through another API.

    Responses

    Request samples

    Content type
    application/json
    {
    • "service_name": "OpenWeather",
    • "api_url": "https://api.example.com",
    • "auth_type": "api_key",
    • "api_key": "string",
    • "auth_token": "string",
    • "auth_send_medium": "query_param",
    • "auth_field_name": "Authorization",
    • "login_api_url": "https://api.example.com/login",
    • "login_api_request_type": "POST",
    • "login_cred_send_medium": "body",
    • "login_credentials": "{\"user_name\":\"abc@gmail.com\",\"password\":\"1234\"}",
    • "login_cred_validation_time": 1600,
    • "auth_field_name_in_resp": "authtoken",
    • "auth_prefix": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "service_id": "string",
    • "status": "string"
    }

    Admin User Management

    Admin User Management

    Creates the new user in user email mobile user pool

    This API creates a new user in user email mobile user pool. Only Email is supported as user name. Here the role is disjoint of the flags the user need to explicitly assign the required role.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    Request Body schema: application/json
    required

    Request body for creating new user

    user_name
    required
    string

    Valid email address or valid phone number

    super_admin
    boolean

    If set to true, User gets Super Admin priviledges
    Is applicable only when RBAC is disabled for the environment

    admin
    boolean

    If set to true, User gets Admin priviledges
    Is applicable only when RBAC is disabled for the environment

    quota
    number >= 1
    Deprecated
    roles
    Array of strings

    Set of roles
    Is applicable only when RBAC is enabled for the environment

    verify_auth_code
    boolean

    If set to true, User gets email verification code

    tags
    Array of strings

    Set of tags to be attached to User

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "user_name": "username@domain.com",
    • "super_admin": true
    }

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "description": "Success description"
    }

    Updates the user in user email mobile user pool

    This API updates the permissions and quota of the user in user email mobile user pool.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    Request Body schema: application/json
    required

    Request body for updating name of the user

    user_name
    required
    string

    Valid email address or valid phone number

    super_admin
    boolean

    If set to true, User gets Super Admin priviledges
    Is applicable only when RBAC is disabled for the environment

    admin
    boolean

    If set to true, User gets Admin priviledges
    Is applicable only when RBAC is disabled for the environment

    quota
    number >= 1
    Deprecated
    roles
    Array of strings

    Set of roles
    Is applicable only when RBAC is enabled for the environment

    verify_auth_code
    boolean

    If set to true, User gets email verification code

    tags
    Array of strings

    Set of tags to be attached to User

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "user_name": "user@domain.com",
    • "super_admin": false
    }

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "description": "Success description"
    }

    Fetches the details of a user

    This API fetches all the internal users by default. If user name is provided then user_id, user_name, super_admin flag, quota, user roles, URL of profile picture and name of that user is returned.

    The super_admin flag is returned only when the user is a super admin, in other cases, it will not be returned in the output.
    Also the picture_url and name are not returned in the output, if it is not set by the user.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    user_name
    string

    user_name of the user whose details are to be fetched.
    If full email is unknown, prefix of the email can be used to list Users.

    user_id
    string

    user_id of the user whose details are to be fetched.

    start_id
    string

    use next_id from the response as start_id to fetch the next set of records. A combination of userID and user name.

    num_records
    number
    Default: 25

    number of users to fetch

    Responses

    Response samples

    Content type
    application/json
    Example
    {
    • "users_list": [
      ],
    • "next_id": "string",
    • "total": 25
    }

    Deletes user account

    This API can be used by admin-users to delete other users account. Here are the details-

    • If the 'request' query param is true, user delete request is initiated and verification code is sent to the invoking user email.
    • If 'verification_code' query param is specified, user account is deleted.
    • The 'super_admin' flag has higher priority over 'admin' flag.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    request
    boolean
    Default: false

    if delete user request is to be initiated, value of request param should be true.

    verification_code
    number
    Default: "<verification_code>"

    if delete user request is to be verified and user account is to be deleted, the verification code received by user should be entered as value of verification_code query param.

    user_name
    required
    string

    user_name of the user who needs to be deleted

    Responses

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "description": "Success description"
    }

    Node Certificate CA

    Node Certificate CA management

    Uploads node certificate's CA

    This API uploads the node CA certificate

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    Request Body schema: application/json
    required
    node_ca_certificate
    required
    string

    The CA(s) of node certificates which are generated using admin CLI and node registration module

    Responses

    Request samples

    Content type
    application/json
    {
    • "node_ca_certificate": "-----BEGIN CERTIFICATE-----<>-----END CERTIFICATE-----"
    }

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "description": "Success description"
    }

    Get all node certificate CAs

    This API gets the node CA certificates

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    Responses

    Response samples

    Content type
    application/json
    {
    • "node_ca_certificate": "-----BEGIN CERTIFICATE-----<>-----END CERTIFICATE-----"
    }

    Webhook Integration

    API to manage the configuration for Webhook integration.

    This API adds new webhook for specified integration.

    This API adds new webhook for specified service name, endpoint and whether its enabled or not.

         Service Name : Name of external service to be integrated

         Endpoint Name : A Service may have more than Webhook Endpoints. Endpoint Name of Service which we are integrating to 

         Enabled : This flag tells whether this integration is enabled

     

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    Request Body schema: application/json
    required

    request body for creating new Webhook Integration.

    service_name
    required
    string

    Name of external service to be integrated

    endpoint_name
    required
    string

    Endpoint name of the service

    enabled
    required
    boolean

    This flag tells whether this integration is enabled or not

    Responses

    Request samples

    Content type
    application/json
    {
    • "service_name": "gva",
    • "endpoint_name": "request_sync",
    • "enabled": true
    }

    Response samples

    Content type
    application/json
    {
    • "status": "success"
    }

    This API updates existing webhook configuration.

    This API updates existing webhook configuration for specified integration and its endpoint.

         Service Name : Name of external service to be integrated

         Endpoint Name : A Service may have more than Webhook Endpoints. Endpoint Name of Service which we are integrating to 

         Enabled : This flag tells whether this integration is enabled

     

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    Request Body schema: application/json
    required

    Request body for updating existing Webhook Integration configuration.

    service_name
    required
    string

    Name of external service to be integrated

    endpoint_name
    required
    string

    Endpoint name of the service

    enabled
    required
    boolean

    This flag tells whether this integration is enabled or not

    Responses

    Request samples

    Content type
    application/json
    {
    • "service_name": "gva",
    • "endpoint_name": "request_sync",
    • "enabled": true
    }

    Response samples

    Content type
    application/json
    {
    • "status": "success"
    }

    Get webhook information.

    This API will get the integration information of webhook.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    service_name
    string
    Example: service_name=mobile_push_notification, gva, alexa

    Name of external service

    endpoint_name
    string

    Endpoint Name of the Service

    Responses

    Response samples

    Content type
    application/json
    {
    • "webhooks_endpoints": [
      ],
    • "total": 1
    }

    This API removes the webhooks configured for integration.

    This API allows admin to remove configured webhooks for integration.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    service_name
    required
    string
    Example: service_name=mobile_push_notification, gva, alexa

    Name of external service

    endpoint_name
    required
    string

    Endpoint Name of the Service

    Responses

    Response samples

    Content type
    application/json
    {
    • "status": "success"
    }

    Get webhook event mapping information.

    This API will get the webhook integration mapping (Beta- These APIs are in development stage and may have breaking changes)

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    webhook_name
    string

    Webhook to be retrieved

    Responses

    Response samples

    Content type
    application/json
    {
    • "webhook_event_mappings": [
      ]
    }

    This API adds webhook event mapping

    This API adds the webhook event mapping (Beta- These APIs are in development stage and may have breaking changes)

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    Request Body schema: application/json

    request body for adding a webhook event mapping.

    webhook_name
    required
    string <= 1024 characters

    Webhook Name

    event_name
    required
    string <= 1024 characters

    Event name

    Responses

    Request samples

    Content type
    application/json
    {
    • "webhook_name": "gva",
    • "event_name": "user_node_association"
    }

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "description": "Success description"
    }

    This API removes webhook event mapping

    This API removes the webhook event mapping (Beta- These APIs are in development stage and may have breaking changes)

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    webhook_name
    required
    string

    Webhook to be removed

    event_name
    required
    string

    Event to be removed

    Responses

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "description": "Success description"
    }

    Statistical Service

    Rainmaker Statistical Service APIs

    This API is used to get the statistical info

    This API is used to get the statistical information for the various Rainmaker operational parameters like, number of registered users or number of registered nodes, etc. This information can be queried based on the parameter name and the duration.
    The metrics data can be retrieved based on daily count, weekly count, monthly count or yearly count. Only one duration parameter can be specified as the query parameter.

    1. If none of these stats parameters or duration is specified in the request parameter, then the values for all the stats parameters with their total count is returned as the response.
    2. Daily Count - The start_date and end_date parameters are used to specify the date range, which is only applicable for daily_count. The difference between start and end dates can be maximum of 31 days and the end_date must be strictly greater than the start_date. The start date and end date should be specified in the YYYY-MM-DD format.
    3. Weekly Count - The start_month, start_year, end_month, end_year parameters are used to specify the date range for weekly_count. The weekly data can be queried for upto 3 Months
    4. Monthly Count - The start_month, start_year, end_month, end_year parameters are used to specify the date range for monthly_count. The monthly data can be queried for upto 12 Months
    5. Yearly Count - The start_year, end_year parameters are used to specify the date range for yearly_count. The yearly data can be queried for upto 5 years.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    metric_name
    string
    Example: metric_name=num_offline_nodes,num_registered_nodes,num_registered_users

    There are various metrics supported. They are -

  • num_registered_users
  • num_registered_nodes
  • num_users_with_nodes
  • num_users_without_nodes
  • num_timed_out_node_association_reqs
  • num_claimed_nodes
  • num_online_nodes
  • num_offline_nodes
    • Multiple stats parameters can be retrieved in one request, these parameters need to be separated by comma in the request.

    duration
    string
    Example: duration=daily_count

    This parameter is user to set the duration of the count .They can be -

  • daily_count
  • weekly_count
  • monthly_count
  • yearly_count
    • Multiple duration parameters cannot be specified in one request

    start_date
    string
    Example: start_date=2020-04-07

    This parameter is used to set the start_date, which is applicable only for daily_count. The expected Format for start_date is YYYY-MM-DD

    end_date
    string
    Example: end_date=2020-04-07

    This parameter is used to set the end_date, which is applicable only for daily_count. The expected Format for end_date is YYYY-MM-DD

    start_month
    string
    Example: start_month=December

    This parameter is used to set the start_month, which is applicable only for weekly_count and monthly_count. The expected Format for start_month is month name like January. This field is case-insensitive.

    end_month
    string
    Example: end_month=December

    This parameter is used to set the end_month, which is applicable only for weekly_count and monthly_count. The expected Format for end_month is month name like January. This field is case-insensitive.

    start_year
    string
    Example: start_year=2020

    This parameter is used to set the start_year, which is applicable only for weekly_count, monthly_count and yearly_count. The expected Format for start_year is YYYY

    end_year
    string
    Example: end_year=2020

    This parameter is used to set the end_year, which is applicable only for weekly_count, monthly_count and yearly_count. The expected Format for end_year is YYYY

    timezone
    string
    Default: "UTC"
    Example: timezone=Asia/Calcutta

    This parameter is used to set the timezone(location) from where the query is made, based on IANA Tz Database name. TimeZone can also be provided like EST but location name is preferred. This field is case-insensitive.

    type
    string
    Example: type=light

    This parameter is used to query for the counts of a specific node type.
    Only supported by num_online_nodes, num_offline_nodes, num_claimed_nodes and num_registered_nodes.

    model
    string
    Example: model=RGB_bulb

    This parameter is used to query for the counts of a specific node model.
    Requires type parameter to use.
    Only supported by num_online_nodes, num_offline_nodes, num_claimed_nodes and num_registered_nodes.

    Responses

    Response samples

    Content type
    application/json
    Example
    {
    • "num_registered_users": {
      },
    • "num_registered_nodes": {
      },
    • "num_users_with_nodes": {
      },
    • "num_users_without_nodes": {
      },
    • "num_timed_out_node_association_reqs": {
      },
    • "num_claimed_nodes": {
      },
    • "num_online_nodes": 10,
    • "num_offline_nodes": 12
    }

    To Initialize data for stats service

    This API is used to initialize data onto the stats table.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    Responses

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "description": "Success description"
    }

    Mail Delivery Failure Logs

    APIs to fetch the email failure logs

    Get the logs of failures occurred while sending emails

    This API is used to fetch the details of failure occurred while sending emails to users. Mail failure logs can be fetched by reciepent email ID or Failure Type(Bounce/Complaint/Delivery).Pagination is supported with num_records and start_id query parameters. timestamp query param can be used to fetch records after that timestamp.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    email_id
    string
    Example: email_id=abc@xyz.com

    Email-Id of the user

    failure_type
    string
    Enum: "Bounce" "Complaint" "Delivery"

    Email failure type

    timestamp
    string
    Example: timestamp=1645623129

    Epoch time from which you want to get the email failures

    start_id
    string
    Example: start_id=abd@domain.com

    use next_id from the response as start_id to fetch the next set of records

    num_records
    string
    Default: 25
    Example: num_records=10

    number of records to fetch

    Responses

    Response samples

    Content type
    application/json
    {
    • "mail_failure_records": [
      ],
    • "next_id": "abd@domain.com"
    }

    API Gateway Stage

    Update API Gateway stage

    Upgrade Rainmaker APIs

    This API is used to upgrade the APIs after RainMaker is upgraded to the newer version.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    Responses

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "description": "Success description"
    }

    Terms Policy

    Operations on Terms of Use and Privacy Policys text files

    Update Terms of Use and Privacy Policy HTML Files

    This API is used to update or create Terms of Use and Privacy Policy HTML files.The URLs of files are given in response.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    Request Body schema: application/json

    Either terms_of_use or privacy_policy needs to be specified

    terms_of_use
    string
    privacy_policy
    string

    Responses

    Request samples

    Content type
    application/json
    {
    • "terms_of_use": "Terms of Use file content",
    • "privacy_policy": "Privacy Policy file content"
    }

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "terms_of_use_file_url": "terms_of_use_file_url",
    • "privacy_policy_file_url": "privacy_policy_file_url"
    }

    Get Terms of Use and Privacy Policy Files content and URL

    This API is used to get content and URL of Terms of Use and Privacy Policy files.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    file
    string
    Example: file=<file_name>

    File which is to be fetched in response.
    Allowed values are - 'privacy_policy' and 'terms_of_use'

    Responses

    Response samples

    Content type
    application/json
    {
    • "terms_of_use": {
      },
    • "privacy_policy": {
      }
    }

    Delete Terms of Use and Privacy Policy Files

    This API is used to delete Terms of Use and Privacy Policy files.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    file
    required
    string
    Example: file=<file_name>

    Name of file which is to be deleted.
    Allowed values are - 'privacy_policy' and 'terms_of_use'

    Responses

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "description": "Success description"
    }

    Cloudwatch Log IAM user

    Add or remove IAM user with permission to read cloudwatch Logs

    Add IAM user with read permission for CloudWatch logs

    This API is used to add an IAM user, with permission to read the cloudwatch logs from AWS account. The logs will be used by the IAM user for debugging purpose. API creates IAM user in AWS account and sends mail to IAM user giving login details.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    Request Body schema: application/json

    'email' is required parameter.

    email
    string

    Responses

    Request samples

    Content type
    application/json
    {
    • "email": "iam user email address"
    }

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "description": "Success description"
    }

    Add IAM user with read permission for CloudWatch logs

    This API is used to remove an IAM user, with permission to read the cloudwatch logs from AWS account.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    email
    required
    string

    email address of IAM user to be deleted

    Responses

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "description": "Success description"
    }

    Log level

    Operations on loglevel

    Change log level

    This API is used to change the log level configuration of one or all lambda functions

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    function_name
    string

    Lambda function name

    loglevel
    required
    string

    Log level to be set Info, Warn, Debug or Error

    Responses

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "description": "Success description"
    }

    Rainmaker Deployment capabilities

    Operations for rainmaker capabilities

    Adds a rainmaker capability

    This API is used to add a capability using name and value

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    Request Body schema: application/json
    Array
    name
    required
    string
    value
    required
    string

    Responses

    Request samples

    Content type
    application/json
    []

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "description": "Success description"
    }

    Fetches a rainmaker capability

    This API is used to get rainmaker capability using capability name

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    name
    string

    The rainmaker capability name to be fetched

    Responses

    Response samples

    Content type
    application/json
    Example
    []

    API Statistics

    Get the API Statistics

    This API is used to get the API Statistics

    This API is used to get the statistics for the RainMaker APIs called by clients like Mobile App, Dashboard, etc. Ex: /v1/user, /v1/user/nodes, etc. This information can be queried based on API Path, method and aggregation interval.
    The data can be retrieved for different aggregation intervals like day, week, month or year and start_time and end_time to specify the date and time range.

    1. Day - Max Interval: 31 days and end_time must be strictly greater than the start_time.
    2. Week - Max Interval: 12 weeks.
    3. Month - Max Interval: 12 months
    4. Year - Max Interval: 3 years

    How Does the API function?

    1. By Default with no parameters passed the API returns the API count for previous day.
    2. To get count for aggregation interval day, week, month, year provide repective aggregate, aggregation_interval, start_time, end_time
      1. Start time and end time is used to provide the timeframe for these queries.
      2. API path and method can be used in conjunction with group by.
    3. To get top 10 API's called or top 10 users calling the API for a given time duration using num_records and group_by.
      1. Start time and end time is used to provide the timeframe, aggregation interval is not supported for these queries.
      2. API path and method can be used in conjunction with group by.
      3. Max Interval: 31 days

    Note:

  • If aggregation interval is provided then start_time and end_time needs to be provided for each query.
  • The Range of data that is retrieved are [StartTime,EndTime)
  • When using start_id the inputs passed (apart from start_id and num_records) need to be kept the same for every call.

    • Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    api_path
    string
    Example: api_path=/v1/user

    This parameter is used to specify the API path for which count needs to be returned.
    / is a special charecter and encoded as %2F while sending the query parameter

    method
    string
    Example: method=POST

    Supported methods are -

  • POST
  • PUT
  • GET
  • DELETE
    • A single valid method need to be passed.

    aggregation_interval
    string
    Default: "day"
    Example: aggregation_interval=day

    This parameter is used to specify the aggregation interval for the params. They can be -

  • day
  • week
  • month
  • year

    • aggregate
    string
    Default: "count"
    Example: aggregate=count

    Following aggregate functions are supported -

  • count - Returns the number of calls made for the given aggregation interval and time range

    • Only one aggregate function can be specified at a time.

    start_time
    number
    Example: start_time=1628557200

    This parameter is used to set the start time. The expected Format for start time is epoch time in seconds. Ex: 1628557200

    end_time
    number
    Example: end_time=1628557200

    This parameter is used to set the end time. The expected Format for end_date is epoch time in seconds. Ex: 1628557200

    week_start
    string
    Default: "Monday"
    Example: week_start=Monday

    This parameter is used to specify the start day of the week. This field is case insensitive. Only applicable in cases were the aggregation interval value is week.

    start_id
    string

    This parameter is used for pagination.
    The pagination token can be used for up to 5 Query Invocations, OR for a duration of up to 1 hour whichever comes first.

    num_records
    number <= 25
    Default: 25

    This parameter is used for pagination and to get top 10 or 20 records.

    group_by
    string
    Example: group_by=api_path

    This parameter is used to set the field for which the top records are to returned. This field is case-insensitive.
    Valid values are:

  • api_path
  • user

    • Responses

    Response samples

    Content type
    application/json
    Example
    {
    • "api_stats": [
      ]
    }

    MQTT Statistics

    Get the MQTT Statistics

    This API is used to get the MQTT Statistics

    This API is used to get the Statistics for the messages posted by nodes to various MQTT topics like node/+/config, node/+/params/local, etc. and node ID.This information can be queried based on aggregation interval.
    The data can be retrieved for different aggregation intervals like day, week, month or year and start_time and end_time to specify the date and time range.

    1. Day - Max Interval: 31 days and end_time must be strictly greater than the start_time.
    2. Week - Max Interval: 12 weeks.
    3. Month - Max Interval: 12 months
    4. Year - Max Interval: 3 years

    How Does the API function?

    1. By Default with no parameters passed the API returns the MQTT message count for previous day.
    2. To get count for aggregation interval day, week, month, year provide repective aggregate, aggregation_interval, start_time, end_time
      1. Start time and end time is used to provide the timeframe for these queries.
      2. MQTT topic and/or node ID can be used in conjunction with group by.
    3. To get top 10 MQTT topics called or top 10 node Ids sending the messages over MQTT topics for a given time duration using num_records and group_by.
      1. Start time and end time is used to provide the timeframe, aggregation interval is not supported for these queries.
      2. MQTT topic and/or Node ID can be used in conjunction with group by.
      3. Max Interval: 31 days

    Note:

  • If aggregation interval is provided then start_time and end_time needs to be provided for each query.
  • The Range of data that is retrieved are [StartTime,EndTime)
  • When using start_id the inputs passed (apart from start_id and num_records) need to be kept the same for every call.

    • Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    topic_name
    string
    Example: topic_name=node/+/config

    This parameter is used to specify the MQTT topic name for which count needs to be returned.
    / and + is a special charecter and encoded as %2F and %2B respectively while sending the query parameter.
    Valid topic names are:

    • $aws/events/presence/disconnected/+
    • $aws/events/presence/connected/+
    • node/+/params/local/init
    • node/+/config
    • node/+/otafetch
    • node/+/otastatus
    • node/+/alert
    • node/+/params/local
    • node/+/alert
    • node/+/user/mapping
    • node/+/params/remote
    • node/+/otaurl
    • node/+/tsdata
    • node/+/from-node

    node_id
    string
    Example: node_id=<node_id>

    node IDs which are sending messages over MQTT topics

    aggregation_interval
    string
    Default: "day"
    Example: aggregation_interval=day

    This parameter is used to specify the aggregation interval for the params. They can be -

  • day
  • week
  • month
  • year

    • aggregate
    string
    Default: "count"
    Example: aggregate=count

    Following aggregate functions are supported -

  • count - Returns the number of calls made for the given aggregation interval and time range

    • Only one aggregate function can be specified at a time.

    start_time
    number
    Example: start_time=1628557200

    This parameter is used to set the start time. The expected Format for start time is epoch time in seconds. Ex: 1628557200

    end_time
    number
    Example: end_time=1628557200

    This parameter is used to set the end time. The expected Format for end_date is epoch time in seconds. Ex: 1628557200

    week_start
    string
    Default: "Monday"
    Example: week_start=Monday

    This parameter is used to specify the start day of the week. This field is case insensitive. Only applicable in cases were the aggregation interval value is week.

    start_id
    string

    This parameter is used for pagination.
    The pagination token can be used for up to 5 Query Invocations, OR for a duration of up to 1 hour whichever comes first.

    num_records
    number <= 25
    Default: 25

    This parameter is used for pagination and to get top 10 or 20 records.

    group_by
    string
    Example: group_by=topic_name

    This parameter is used to set the field for which the top records are to returned. This field is case-insensitive.
    Valid values are:

  • topic_name
  • node_id

    • Responses

    Response samples

    Content type
    application/json
    Example
    {
    • "mqtt_stats": [
      ]
    }

    IAM based Admin User Management

    IAM based Admin User Management

    Admin User Management [Deprecated]

    These APIs are Deprecated. Check the APIs in the 'Admin User Management' group above.

    Creates the new user

    This API creates a new user. Only Email is supported as user name. Here the role is disjoint of the flags the user need to explicitly assign the required role.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    Request Body schema: application/json
    required

    Request body for creating new user

    user_name
    required
    string

    Valid email address or valid phone number

    super_admin
    boolean

    If set to true, User gets Super Admin priviledges
    Is applicable only when RBAC is disabled for the environment

    admin
    boolean

    If set to true, User gets Admin priviledges
    Is applicable only when RBAC is disabled for the environment

    quota
    number >= 1
    Deprecated
    roles
    Array of strings

    Set of roles
    Is applicable only when RBAC is enabled for the environment

    verify_auth_code
    boolean

    If set to true, User gets email verification code

    tags
    Array of strings

    Set of tags to be attached to User

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "user_name": "username@domain.com",
    • "super_admin": true
    }

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "description": "Success description"
    }

    Updates the user

    This API updates the permissions and quota of the user.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    Request Body schema: application/json
    required

    Request body for updating name of the user

    user_name
    required
    string

    Valid email address or valid phone number

    super_admin
    boolean

    If set to true, User gets Super Admin priviledges
    Is applicable only when RBAC is disabled for the environment

    admin
    boolean

    If set to true, User gets Admin priviledges
    Is applicable only when RBAC is disabled for the environment

    quota
    number >= 1
    Deprecated
    roles
    Array of strings

    Set of roles
    Is applicable only when RBAC is enabled for the environment

    verify_auth_code
    boolean

    If set to true, User gets email verification code

    tags
    Array of strings

    Set of tags to be attached to User

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "user_name": "user@domain.com",
    • "super_admin": false
    }

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "description": "Success description"
    }

    Fetches the details of a user

    This API fetches all the internal users by default. If user name is provided then user_id, user_name, super_admin flag, quota, user roles, URL of profile picture and name of that user is returned.

    The super_admin flag is returned only when the user is a super admin, in other cases, it will not be returned in the output.
    Also the picture_url and name are not returned in the output, if it is not set by the user.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    user_name
    string

    user_name of the user whose details are to be fetched.

    start_id
    string

    use next_id from the response as start_id to fetch the next set of records. A combination of userID and user name.

    num_records
    string
    Default: 25

    number of users to fetch

    Responses

    Response samples

    Content type
    application/json
    Example
    {
    • "users_list": [
      ],
    • "next_id": "string",
    • "total": "number"
    }

    Deletes user account

    This API can be used by admin-users to delete other users account. Here are the details-

    • If the 'request' query param is true, user delete request is initiated and verification code is sent to the invoking user email.
    • If 'verification_code' query param is specified, user account is deleted.
    • The 'super_admin' flag has higher priority over 'admin' flag.

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    request
    boolean
    Default: false

    if delete user request is to be initiated, value of request param should be true.

    verification_code
    number
    Default: "<verification_code>"

    if delete user request is to be verified and user account is to be deleted, the verification code received by user should be entered as value of verification_code query param.

    user_name
    required
    string

    user_name of the user who needs to be deleted

    Responses

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "description": "Success description"
    }

    Node Parameter Operations

    Update the Node Parameter

    This API will let admins update the state of the device

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    node_id
    string

    node id

    Request Body schema: application/json
    required

    Request body for updating Node Parameter

    One of
    object
    object

    Responses

    Request samples

    Content type
    application/json
    Example
    [
    • {
      }
    ]

    Response samples

    Content type
    application/json
    {
    • "status": "success",
    • "description": "Success description"
    }

    Get the Node parameter

    This API will Get the state of the device

    Authorizations:
    AccessToken
    path Parameters
    version
    required
    string
    Default: "v1"

    API Version (Current supported API Version is 'v1')

    query Parameters
    node_id
    required
    string

    node id

    Responses

    Response samples

    Content type
    application/json
    {
    • "Light": {
      },
    • "Switch": {
      }
    }