Skip to main content

​
API Access

You will first need access to the NOX Energy API. To receive this, follow the Authentication guide.

​
User creation process

​
1. User creation from the supplier’s website/app

​
1.1 Endpoint

Use the following endpoint to connect a user to our platform and link their asset: Create supplier link session

​
1.2 Authentication flow

Summary:
  1. Call our API → Creates an authentication session; you redirect the user to the link_url.
  2. User chooses brand → NOX Energy opens the brand-specific authentication page.
  3. User authenticates → The user is redirected to the callback URL you provided to our API.
  4. Done! → NOX Energy has a user_id/device_id to supplier_user_id mapping and data is available in our Package API endpoints.
NOX Energy Supplier Authentication Flow Detailed flow: You provide the endpoint your internal user_id for the end-user, a redirect_url where NOX Energy will send the user after the flow, and optionally a language and brand to pre-select the Authenticator UI. This can be your mobile app or website. We use the user_id you provide to map the device with our internal nox user_id and device_id. Example: 
curl --request POST \
  --url https://auth.nox.energy/v2/supplier/link-sessions \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: api_key_123' \
  --data '{
  "user_id": "supplier_user_id_123",
  "redirect_url": "https://your-app.com/callback",
  "language": "en"
}'
On a successful response, you will receive a link_url field. 
{
  "link_url": "https://auth.nox.energy/ui?token=abc123&language=en",
  "link_token": "abc123def456ghi789jkl012mno345pqr678stu901vwx234yz",
  "supplier": "Your Supplier Name",
  "supplier_user_id": "supplier_user_id_123",
  "redirect_url": "https://your-app.com/callback",
  "language": "en",
  "brand": null,
  "completed_at": null,
  "created_at": 1703123456,
  "expires_at": 1703124056
}
Redirect the user to this link_url from your website or app to start the manufacturer authentication flow. NOX Energy Brand Selection On this page the user selects their manufacturer brand, which opens the manufacturer’s OAuth page. The user logs into the manufacturer’s portal to grant access to their asset. Depending on the brand, the user also accepts the manufacturer’s terms of service during this step.

​
1.3 Redirect callback

To complete the integration flow, you must provide NOX Energy with a redirect URL (the redirect_url field in the request). After the user successfully completes the authentication, they are redirected to this URL with query parameters containing the connection details, allowing you to map the NOX user to your system. The redirect URL will contain a ?data= query parameter with a base64url-encoded (no padding) JSON payload: 
https://your-app.com/callback?data=eyJub3hfdXNlcl9pZCI6Ii4uLiIsIC4uLn0
The decoded JSON object has the following structure:
FieldTypeDescription
nox_user_idstringThe NOX subscriber ID.
supplier_user_idstringThe supplier’s user ID from the link session.
brandstringManufacturer brand (lowercase).
device_idsstring[]List of device IDs that were connected.
connected_atintegerUnix timestamp when the connection was made.
Example decoded payload: 
{
  "nox_user_id": "nox_abc123",
  "supplier_user_id": "supplier_user_id_123",
  "brand": "daikin",
  "device_ids": ["device_001", "device_002"],
  "connected_at": 1703123456
}
Note:
  • A link session expires 10 minutes after creation. If the session times out, the authentication will fail even if the user completes it afterwards.
  • If a user authenticates again with the same supplier_user_id, we overwrite the linked device with the new one while keeping the user_id and supplier_user_id the same.
  • If the owner of an asset authenticates using two different supplier_user_id values, only the last user will exist on our side, as we assume a single user has ownership of a device.
  • After a device connects to our system for the first time, we need approximately 30 days of data before we can provide accurate steering capabilities.

​
2. User creation from the manufacturer’s or NOX Energy website/app

When a user enables NOX Energy optimizations from the NOX Energy web app or the manufacturer’s website/app, we redirect the user to an energy supplier selector where they can choose and authenticate with an integrated energy supplier (provided the supplier has an OAuth login page). This allows the energy supplier to know which user_id and device_id are linked to which supplier_user_id. Additionally, if NOX Energy is integrated with both the supplier and the manufacturer, we keep user preferences like comfort temperature bounds in sync between all parties. Below is an example flow diagram: NOX Energy Manufacturer to Supplier Authentication flow

​
2.1 Supplier OAuth page

When the user selects their supplier, they are redirected to an OAuth login page that the supplier must provide. The supplier should configure a redirect URL from their OAuth platform back to NOX. The supplier’s OAuth page should also present the terms and conditions for the user to accept. On successful authentication, the supplier shares the supplier_user_id via the NOX POST /post-login-redirect endpoint. This allows NOX Energy to map the user_id to the supplier_user_id, so the supplier can link devices coming from the NOX or manufacturer app to their users. Note:
  • An authentication session can only last 15 minutes. If the session times out, the authentication will fail even if the user completes it afterwards.

​
2.2 Redirect user

After a successful redirect to the NOX Energy platform, the user is redirected back to the NOX Energy or manufacturer’s website/app through the redirect URL created by the manufacturer at the start of the authentication process. This confirms to the user that the supplier authentication succeeded.