Reserve a node ID for a device
POST/v1/claim/initiate
Assigns a cloud-generated node ID to a device MAC address, creating the reservation when none exists. The node ID is minted before any certificate exists, so certificate identity is server-determined.
Idempotent per {MAC, caller}: a repeat call returns the existing node
ID with 200 instead of 201, and does not count against the caller's
quota. The request mac_addr is never echoed back.
Available only on deployments with assisted claiming enabled; check for
the rmng-claim-core AssistedClaiming output in the published outputs
(absent when the claim group is not deployed). When it is not deployed
these routes do not exist, so a request is rejected at the API Gateway
rather than reaching the service. The 404 below is the service's own
response when claiming is inactive.
Request
Responses
- 200
- 201
- 400
- 401
- 403
- 404
- 500
Existing reservation returned (idempotent repeat)
New reservation created
Bad request
Unauthorized - Invalid or missing authentication
Per-caller node quota reached
Not found - the resource does not exist, or the feature is not enabled on this deployment. For username lookups the message is deliberately generic — it does not reveal whether an address is registered.
Internal server error