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 control device requests are client_id and client_secret, which must be provided via HTTP Basic Authentication. You can view and manage your control devices API keys in the Realer Dashboard when you are signed in as user. If you do not have control device API keys, you can get 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' \
                -H 'Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=='

POST control_devices/sessions.realino

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.

Type: String

Example: Basic QWxhZGRpbjpPcGVuU2VzYW1l

Responses

Code Description

200

Code	Description
200	OK (Success) Example value (application/json) { "code": 2000, "id": 1, "access_token": "b11db7f6c816568eb3b156df3aeaa5", "token_type": "Bearer", "access_token_expires_in": 3600, "refresh_token": "f716247dc11f18f761c380d74fbec0", "model_keyword": "realino_xp_dev", "model_api_v": "2025-02-04", "plan_requests_period_interval": 5, "plan_requests_data_transfer": 5, "subscription_status": "active", "subscription_license_type": "cd_developer_license", "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 authentication 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. In particular, always check that subscription_status is active after authentication, otherwise subsequent requests will fail.
401	Unauthorized (Client Error) Example value (application/json) `{ "code": 4001, "error": "Invalid client id / client secret combination.", "details": {} }`
422	Unprocessable Entity (Client Error) Example value (application/json) `{ "code": 4022 "error": "Fix fields with errors: client id and client secret.", "details": { "client_id": "can't be blank", "client_secret": "can't be blank" } }`

OK (Success)

Example value (application/json)


                        {
                          "code": 2000,
                          "id": 1,
                          "access_token": "b11db7f6c816568eb3b156df3aeaa5",
                          "token_type": "Bearer",
                          "access_token_expires_in": 3600,
                          "refresh_token": "f716247dc11f18f761c380d74fbec0",
                          "model_keyword": "realino_xp_dev",
                          "model_api_v": "2025-02-04",
                          "plan_requests_period_interval": 5,
                          "plan_requests_data_transfer": 5,
                          "subscription_status": "active",
                          "subscription_license_type": "cd_developer_license",
                          "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 authentication 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. In particular, always check that subscription_status is active after authentication, otherwise subsequent requests will fail.

401

Unauthorized (Client Error)

Example value (application/json)


                        {
                          "code": 4001,
                          "error": "Invalid client id / client secret combination.",
                          "details": {}
                        }

422

Unprocessable Entity (Client Error)

Example value (application/json)


                        {
                          "code": 4022
                          "error": "Fix fields with errors: client id and client secret.",
                          "details": {
                            "client_id": "can't be blank",
                            "client_secret": "can't be blank"
                          }
                        }

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.