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 keep them secure. Do not share secret API keys in publicly accessible areas such as GitHub or client-side code.
iot/v1 device requests as Authorization: Bearer <access_token>.
Realer uses OAuth 2.0 Client Credentials Grant because a control device is a machine client acting as itself, not a user approving access on a screen. This is not OAuth Device Authorization Grant.
The OAuth endpoints follow the OAuth wire format: /oauth/token and /oauth/revoke receive form-encoded POST bodies and return JSON responses. Protected iot/v1 HTTPS requests use JSON payloads when a request body exists.
MQTT runtime credentials are short-lived and issued only after OAuth client credentials authentication. Future high-assurance deployments can bind authentication to device-held keys, such as mTLS client certificates or signed client assertions, without changing the public runtime payload contracts.
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'Authenticate a registered control device with OAuth 2.0 Client Credentials Grant and obtain an access token for subsequent device API requests.
Base64 encoding of client_id and client_secret (API keys) joined by a single colon :.
Type: String
Example: Basic QWxhZGRpbjpPcGVuU2VzYW1l
The request body media type.
Value: application/x-www-form-urlencoded
Must be client_credentials.
Type: String
Requested device API scopes. If omitted, the token receives the default HTTPS scopes iot:catalog:read and iot:feed-data:write. See the OAuth scope reference below.
Type: Space-separated string
200 OK
The device receives the Bearer token used for protected HTTPS bootstrap and runtime calls.
{
"access_token": "b11db7f6c816568eb3b156df3aeaa5",
"token_type": "Bearer",
"expires_in": 3600,
"renew_after": 2700,
"scope": "iot:catalog:read iot:feed-data:write"
}400 Bad Request
{
"error": "invalid_request",
"error_description": "grant_type is required",
"request_id": "58f4f1f5-9c02-4f6b-9f0e-4077ed9a9a1b"
}401 Unauthorized
{
"error": "invalid_client",
"error_description": "Invalid client authentication.",
"request_id": "58f4f1f5-9c02-4f6b-9f0e-4077ed9a9a1b"
}broker_url, route topics, and credential endpoint.
The OAuth token response does not include the MQTT broker host or plaintext MQTT credentials.
Request only the scopes your firmware needs. MQTT scopes authorize MQTT credential issue and broker operations; they are not sent inside MQTT packets.
| Scope | Use |
|---|---|
iot:catalog:read |
Read HTTPS command/sensor catalogs and MQTT catalog discovery. See device catalog and MQTT flow. |
iot:feed-data:write |
Write canonical HTTPS feed data. See feed-data ingestion. |
iot:mqtt:connect |
Request short-lived MQTT credentials. See MQTT flow. |
iot:mqtt:desired:read |
Subscribe to command desired-state topics. See MQTT payload reference. |
iot:mqtt:ack:read |
Subscribe to MQTT application acknowledgements. See MQTT payload reference. |
iot:mqtt:feed-data:write |
Publish MQTT command acknowledgements and sensor feed data. See MQTT payload reference. |
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.
Bearer access tokens expire. By default, OAuth access tokens expire after 3600 seconds and the default renewal hint is 2700 seconds. If renewal cannot complete, the device should keep or enter its local safe behavior until cloud authorization is restored. See field semantics for expiry and renewal field rules shared by OAuth tokens and MQTT credentials.
curl "https://api.therealer.com/oauth/revoke" \
-X POST \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \
--data 'token=b11db7f6c816568eb3b156df3aeaa5'Revoke a Bearer access token issued to the authenticated control device. Revocation also invalidates MQTT credentials derived from that access token.
Base64 encoding of client_id and client_secret (API keys) joined by a single colon :.
Type: String
Example: Basic QWxhZGRpbjpPcGVuU2VzYW1l
The request body media type.
Value: application/x-www-form-urlencoded
The Bearer access token to revoke. The endpoint is idempotent and returns success for unknown or already-revoked tokens without exposing token existence.
Type: String
200 OK
A successful revocation returns Cache-Control: no-store, Pragma: no-cache, and an empty JSON object.
{}
Use revocation when a device intentionally shuts down a runtime session, is decommissioned, or may have exposed a token while it can still reach HTTPS.
Normal renewal does not require revocation; request a new token before renew_after.