Skip to main content
API docs by Redocly

ESP RainMaker Claiming Service - API definitions (1.0.0)

Download OpenAPI specification:Download

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

API definitions for ESP RainMaker Claiming Service

Find out more about ESP RainMaker

Stand-alone claiming service

Initiate and Verify APIs for Claiming devices

Initiates the claiming process for devices

This API initiates the claiming process for devices. The user passes a mac_address in the initiate request along with the platform. In the request payload, the platform can be one of the valid platforms. The initiate request generates a claim. In case of authenticated claiming, a node_id is returned in the response. In case of unauthenticated claiming, auth_id and challenge are returned. The access_token can be passed as the authorisation header, it is optional in case of unauthenticated claiming

Valid Platforms are-
1. ESP32
2. ESP32S2
3. ESP32C3
4. ESP32S3
5. ESP32C2
6. ESP32C6
7. ESP32H2 Platforms which supported Unauthenticated Claiming are-
1. ESP32S3
2. ESP32S2
3. ESP32C3
4. ESP32C6
5. ESP32H2

Authorizations:
AccessToken
Request Body schema: application/json
required

Request body for creating new claim initiate request. platform can be one of valid platforms. mac_addr format will be all capitals with no colons in between and having only hex values, e.g. 7CDFA100033B

mac_addr
string

mac_addr format will be all capitals with no colons in between and having only hex values

platform
string

Responses

Request samples

Content type
application/json
{
  • "mac_addr": "string",
  • "platform": "string"
}

Response samples

Content type
application/json
Example
{
  • "node_id": "string"
}

Verification of the claiming request for devices

This API verifies the claiming request for devices. In case of authenticated claiming, the user passes the Certificate Signing Request and the claiming verify API returns the certificate for the device. For unauthenticated claiming, the user passes the auth_id, challenge_response and the Certificate Signing Request in the request. In the response, the device certificate is returned. If there are any failures ( claim quota is insufficient or invalid challenge_response ), an error is returned. The access_token can be passed as the authorisation header, but it is optional for esp32s2

Authorizations:
AccessToken
query Parameters
matter
boolean
Default: false

Indicates whether device certificate should be matter compliant.

test
boolean
Default: false

Applicable only if matter=true. Indicates whether the claiming is done for test.

Request Body schema: application/json
required

Request body for verifying claim request. csr is Certificate Signing Request for node certificate. For unauthenticated claim verify challenge_response and auth_id are required.

One of
csr
string
send_mqtt_host
boolean

Responses

Request samples

Content type
application/json
Example
{
  • "csr": "string",
  • "send_mqtt_host": true
}

Response samples

Content type
application/json
{
  • "certificate": "string",
  • "mqtt_host": "a2w2vjfj9th3iq.ats.iot.<region>.amazonaws.com"
}