Authentication

The Realer API uses the industry standard OAuth 2.0 to authenticate Realino-compliant control device requests.

The Realer API keys used to authenticate requests are client_id and client_secret. You can view and manage your control devices API keys in the Realer Dashboard once you are signed in as user. If you do not have control device API keys, you can request ones.

Your API keys carry many privileges, 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.

Authenticate control device

cURL


              curl "https://www.therealer.com/control_devices/sessions.realino" \
                -X POST \
                -H 'Content-Type: application/json' \
                -d '{"client_id":"123456789012345","client_secret":"7Fjfp0ZBr1KtDRbnfVdmIw3"}'

POST control_devices/sessions.realino

Request parameters

client_id (required)

Client ID of control device that needs to be authenticated. You can request one here.

Type: Integer

Example: 123456789012345

client_secret (required)

Secret key of control device that needs to be authenticated. You can request one here

Type: String

Example: b11db7f6c816568eb3b156df3aeaa5

Request body

Example value (application/json)


              {
                "client_id": 123456789012345,
                "client_secret": "b11db7f6c816568eb3b156df3aeaa5"
              }

Responses

Code	Description
200	OK (Success) Example value (application/json) { "id": 1, "access_token": "b11db7f6c816568eb3b156df3aeaa5", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "f716247dc11f18f761c380d74fbec0", "model_keyword": "realino_xp_dev_trl1_6_v1", "model_api_v": "0.100", "requests_period_interval": 5, "commands": [ { "id": 1, "kind": "relay", "value_type": "binary", "value_type_range_min": "0.0", "value_type_range_max": "1.0", "value_type_range_step": "1.0", "value_type_mu": null, "value_type_pqc": null, "pin_port": "6" }, { "id": 2, "kind": "relay", "value_type": "customary", "value_type_range_min": "5.0", "value_type_range_max": "35.0", "value_type_range_step": "0.5", "value_type_mu": "°C", "value_type_pqc": "Temperature", "pin_port": "9" } ], "sensors": [ { "id": 1, "kind": "thermistor", "pqc": "temperature", "mu": "°C", "pin_port": "14" }, { "id": 2, "kind": "ldr_sensor", "pqc": "illuminance", "mu": "lx", "pin_port": "15" } ] } From the success response, the authenticated device receives data about itself as registered on Realer, including all available commands and sensors. This data is leveraged locally by the control device to interact programmatically with Realer, such as for getting control commands and sending control feeds.
400	Bad Request (Client Error) Example value (application/json) `{ "error": "Param is missing or the value is empty: control_devices_session" }`
401	Unauthorized (Client Error) Example value (application/json) `{ "error": "invalid_client", "error_description": "Invalid client secret / client id combination." }`
422	Unprocessable Entity (Client Error) Example value (application/json) `{ "error": "invalid_request", "error_description": "Fix fields with errors: client secret.", "client_secret": [ "has an invalid format" ] }`

Note: According to the oAuth Protocol, the Access Token must be refreshed time by time. It is up to the Realino-compliant control device to determine when an Access Token is expired (not longer valid). By default, the Access Token issued for Realino-compliant control devices expires after 3600 seconds. The control device can refresh the Access Token by executing a new authentication request.