New Asset Integration

Use this path when you don’t yet have your own connection to a specific asset type. NOX Energy brokers the connection for you: we redirect the user to our Authenticator UI, where they authenticate directly with the relevant party, and hand you back a mapping to your own user.

Already have your own connection to the asset type? See Bring Your Own Connection instead.

Energy Supplier
Manufacturer/EMS

Endpoint

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

Authentication flow

Summary:

Call our API → Creates an authentication session; you redirect the user to the link_url.
User chooses brand → NOX Energy opens the brand-specific authentication page.
User authenticates → The user is redirected to the callback URL you provided to our API.
Done! → NOX Energy has a user_id/device_id to supplier_user_id mapping and data is available in our API endpoints.

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, the asset_type of the device to connect, 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.

Choosing the device type (`asset_type`)

The required asset_type field tells NOX Energy which kind of device the user is connecting. It also determines which manufacturer brands are shown in the Authenticator UI. Supported values:

`asset_type`	Device category	Examples
`hp`	Heat pump	daikin, vaillant, nibe, …
`pv`	PV solar inverter	sma, solis, huawei, …

To connect a PV (solar) device, set "asset_type": "pv". The user will then only see PV inverter brands. To connect a heat pump, set "asset_type": "hp". If you also pass a brand in the link-session request, then you will directly go to that brand’s connect page instead of first arriving to the brand selector page. This can be useful if you want to have your own style of brand selector within your app. Note that the provided brand must be a valid brand for the chosen asset_type. See the Supported Assets Overview for the full list of brands per category.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",
  "asset_type": "hp",
  "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",
  "asset_type": "hp",
  "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.

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.

Redirect callback

To complete the integration flow, you must provide NOX Energy with a redirect URL (the redirect_url field in the request). It must be a valid http(s) URL, and any query parameters you include in it are preserved.When the user finishes the flow they are redirected back to this URL. We always append a success query parameter so a single redirect URL can render both outcomes:

Success — ?success=true plus a data query parameter (see below).
Failure — ?success=false, with no data parameter (this includes errors such as the user declining consent on the manufacturer’s OAuth screen).

https://your-app.com/callback?success=true&data=eyJub3hfdXNlcl9pZCI6Ii4uLiIsIC4uLn0
https://your-app.com/callback?success=false

On success the data parameter holds a base64url-encoded (no padding) JSON payload with the connection details, allowing you to map the NOX user to your system. The decoded JSON object has the following structure:

Field	Type	Description
`nox_user_id`	string	The NOX subscriber ID.
`supplier_user_id`	string	The supplier’s user ID from the link session.
`brand`	string	Manufacturer brand (lowercase).
`asset_type`	string	Device category (e.g. `hp`, `pv`).
`device_ids`	string[]	List of device IDs that were connected.
`connected_at`	integer	Unix timestamp when the connection was made.

Example decoded payload:

{
  "nox_user_id": "nox_abc123",
  "supplier_user_id": "supplier_user_id_123",
  "brand": "daikin",
  "asset_type": "hp",
  "device_ids": ["device_001", "device_002"],
  "connected_at": 1703123456
}

Data availability after connecting

Completing the Authenticator flow does not guarantee that device data is immediately available. After the device is connected to NOX Energy, the connection may still need to finalize on the connected device’s manufacturer (OEM) side before we are granted the access rights required to export device data to the connecting party.As a result, the /devices endpoint may return an empty result right after the user completes the link session.

We advise the connecting party to poll the /devices endpoint for up to 10 minutes after the redirect callback, while displaying a pending state to the end user. Once device data is returned, the connection is finalized and you can stop polling. If no device data is returned after 10 minutes, assume something went wrong with the connection.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.

Endpoint

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

A manufacturer-specific link session endpoint exists but will be deprecated in the future.

Looking to link your users to a NOX-integrated energy supplier instead? See the OEM to Supplier Integration (BETA) guide.

Authentication flow

Summary:

Call our API → Creates an authentication session; you redirect the user to the link_url.
User chooses brand → NOX Energy opens the brand-specific authentication page.
User authenticates → The user is redirected to the callback URL you provided to our API.
Done! → NOX Energy has a user_id/device_id to partner_user_id mapping and data is available in our API endpoints.

Choosing the device type (`asset_type`)

The required asset_type field tells NOX Energy which kind of device the user is connecting. It also determines which manufacturer brands are shown in the Authenticator UI. Supported values:

`asset_type`	Device category	Examples
`hp`	Heat pump	daikin, vaillant, nibe, …
`pv`	PV solar inverter	sma, solis, huawei, …

curl --request POST \
  --url https://auth.nox.energy/v2/partner/link-sessions \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: api_key_123' \
  --data '{
  "user_id": "partner_user_id_123",
  "redirect_url": "https://your-app.com/callback",
  "asset_type": "hp",
  "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",
  "partner": "Your Company Name",
  "partner_user_id": "partner_user_id_123",
  "redirect_url": "https://your-app.com/callback",
  "language": "en",
  "asset_type": "hp",
  "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.

Redirect callback

Success — ?success=true plus a data query parameter (see below).
Failure — ?success=false, with no data parameter (this includes errors such as the user declining consent on the manufacturer’s OAuth screen).

https://your-app.com/callback?success=true&data=eyJub3hfdXNlcl9pZCI6Ii4uLiIsIC4uLn0
https://your-app.com/callback?success=false

Field	Type	Description
`nox_user_id`	string	The NOX subscriber ID.
`partner_user_id`	string	The partner’s user ID from the link session.
`brand`	string	Manufacturer brand (lowercase).
`asset_type`	string	Device category (e.g. `hp`, `pv`).
`device_ids`	string[]	List of device IDs that were connected.
`connected_at`	integer	Unix timestamp when the connection was made.

Example decoded payload:

{
  "nox_user_id": "nox_abc123",
  "partner_user_id": "partner_user_id_123",
  "brand": "daikin",
  "asset_type": "hp",
  "device_ids": ["device_001", "device_002"],
  "connected_at": 1703123456
}

Data availability after connecting

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 partner_user_id, we overwrite the linked device with the new one while keeping the user_id and partner_user_id the same.
If the owner of an asset authenticates using two different partner_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.

Get Started

Integration

Package Guides

Features

Endpoint

Authentication flow

Choosing the device type (`asset_type`)

Redirect callback

Data availability after connecting

Endpoint

Authentication flow

Choosing the device type (`asset_type`)

Redirect callback

Data availability after connecting

​Endpoint

​Authentication flow

​Choosing the device type (asset_type)

​Redirect callback

​Data availability after connecting

​Endpoint

​Authentication flow

​Choosing the device type (asset_type)

​Redirect callback

​Data availability after connecting

Endpoint

Authentication flow

Choosing the device type (`asset_type`)

Redirect callback

Data availability after connecting

Endpoint

Authentication flow

Choosing the device type (`asset_type`)

Redirect callback

Data availability after connecting