Authentication

The Realer API authenticates device requests with OAuth 2.0 Client Credentials Grant. Control devices exchange their API keys for a Bearer access token, then use that token on protected iot/v1 requests.

The Realer API keys used to authenticate control device requests are client_id and client_secret, which must be provided via HTTP Basic Authentication. You can view and manage your control device API keys in the Realer Dashboard when you are signed in as a user. If you do not have control device API keys, you can get them.

Your client credentials can issue device access tokens, so be sure to keep them secure. Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

The OAuth token endpoint issues Bearer access tokens for the canonical device API. Use the returned access token for iot/v1 device requests as Authorization: Bearer <access_token>.

Authenticate control device

cURL


              curl "https://api.therealer.com/oauth/token" \
                -X POST \
                -H 'Content-Type: application/x-www-form-urlencoded' \
                -H 'Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \
                --data 'grant_type=client_credentials&scope=iot:catalog:read%20iot:feed-data:write'

POST /oauth/token

Authenticate a registered control device with OAuth 2.0 Client Credentials Grant and obtain an access token for subsequent device API requests.

Request headers

Authorization (required)

Base64 encoding of client_id and client_secret (API keys) joined by a single colon ":" of the control device that needs to be authenticated. Control-device client_id values begin with cdv_ and contain 30 characters.

Type: String

Example: Basic QWxhZGRpbjpPcGVuU2VzYW1l

Request body

grant_type (required)

Must be client_credentials.

Type: String

scope (optional)

Requested device API scopes. Supported scopes are iot:catalog:read and iot:feed-data:write. If omitted, the token receives both scopes.

Type: Space-separated string

Responses

Code Description

200

Code	Description
200	OK (Success) Example value (application/json) `{ "access_token": "b11db7f6c816568eb3b156df3aeaa5", "token_type": "Bearer", "expires_in": 3600, "renew_after": 2700, "scope": "iot:catalog:read iot:feed-data:write" }` From the successful token response, the authenticated device receives the access token required for subsequent API calls. Retrieve command and sensor catalogs through the device catalog endpoints, then send measurements and acknowledgements through feed-data ingestion. Subscription and plan checks are enforced on the protected `iot/v1` resources. Use the `renew_after` value to start renewal before the access token expires. If the access token expires before renewal succeeds, authenticate again with the same OAuth token endpoint and `grant_type=client_credentials`.
400	Bad Request (Client Error) Example value (application/json) `{ "error": "invalid_request", "error_description": "grant_type is required", "request_id": "58f4f1f5-9c02-4f6b-9f0e-4077ed9a9a1b" }`
401	Unauthorized (Client Error) Example value (application/json) `{ "error": "invalid_client", "error_description": "Invalid client authentication.", "request_id": "58f4f1f5-9c02-4f6b-9f0e-4077ed9a9a1b" }`

OK (Success)

Example value (application/json)



                        {
                          "access_token": "b11db7f6c816568eb3b156df3aeaa5",
                          "token_type": "Bearer",
                          "expires_in": 3600,
                          "renew_after": 2700,
                          "scope": "iot:catalog:read iot:feed-data:write"
                        }

From the successful token response, the authenticated device receives the access token required for subsequent API calls. Retrieve command and sensor catalogs through the device catalog endpoints, then send measurements and acknowledgements through feed-data ingestion. Subscription and plan checks are enforced on the protected iot/v1 resources.

Use the renew_after value to start renewal before the access token expires. If the access token expires before renewal succeeds, authenticate again with the same OAuth token endpoint and grant_type=client_credentials.

400

Bad Request (Client Error)

Example value (application/json)


                        {
                          "error": "invalid_request",
                          "error_description": "grant_type is required",
                          "request_id": "58f4f1f5-9c02-4f6b-9f0e-4077ed9a9a1b"
                        }

401

Unauthorized (Client Error)

Example value (application/json)


                        {
                          "error": "invalid_client",
                          "error_description": "Invalid client authentication.",
                          "request_id": "58f4f1f5-9c02-4f6b-9f0e-4077ed9a9a1b"
                        }

Note: Bearer access tokens expire. A control device should track expires_in and start renewal after renew_after seconds. By default, OAuth access tokens expire after 3600 seconds. The default renewal hint is 2700 seconds. The control device obtains a new access token by executing a new Client Credentials token request. If renewal cannot complete, the device should keep or enter its local safe behavior until cloud authorization is restored.