Authentication
For a client to be allowed to communicate with the NIBE Uplink API it needs to be registered with NIBE Uplink. When registering a client a client key and a client secret are generated and supplied to the client owner. It is up to the client owner to make sure these are not leaked to a third party. If the client owner suspects the client key and secret could have been leaked, it is the client owner's responsibility to notify the NIBE Uplink team about the potential leak in order to block any malicious activity done in the name of their client.
User Authentication
Currently, all requests to the NIBE Uplink API requires a valid user authentication. The user authentication makes sure that the client can only access the resources for that particular user.
Users are authenticated via the OAuth 2 protocol. NIBE Uplink currently supports the Authorization Code Grant flow and the Implicit Grant flow. The Authorization Code Grant flow targets clients which the OAuth 2 specification deems confidential, such as web applications and mobile apps while the Implicit Grant flow is a shorter flow which targets public clients that can't keep the confidentiality of the OAuth credentials, such as browser based JavaScript applications.
Under no circumstances is the client allowed to process or handle a user's secret login credentials.
The following URL:s are used for the OAuth 2 requests
Authorize endpoint
https://api.nibeuplink.com/oauth/authorize Token endpoint
https://api.nibeuplink.com/oauth/tokenScope
When authenticating with the NIBE Uplink API you need to specify how your application wants to access the API through the Scope parameter. Depending on which scopes you have requested and have been granted by the user you will have access to different functionality. Each function in the function list clearly specifies which scope is required in order to access that particular function.
Scope Description
READSYSTEM Gives access to reading system status and stored parameters
WRITESYSTEM Gives access to change settings on systems
Authentication Examples
Example: Authorization Code Grant
The Authorization Code Grant takes place in 4 steps as outlined below. Before starting to authenticate you need to have registered your application and received a client id and secret.
1. Redirect the user's browser to the OAuth2 authorization page.
Redirect the user's browser to the address outlined below. Make sure to exchange the [CLIENT_ID], [SCOPES] and [REDIRECT_URI] with the correct values for your application.
https://api.nibeuplink.com/oauth/author ... client_id=[CLIENT_ID]&scope=[SCOPES]&redirect_uri=[REDIRECT_URI]&state=[STATE]
2. The user authorizes your application.
The user will now be prompted with a login form (if not already logged in) and the question whether they would like to give your application access to their data.
3. The user is redirected to your application with authorization data.
When the user has authorized your application he/she will be redirected back to the redirect_uri you specified to the authorize endpoint with the data you need to gain access to the account. Always check that the state parameter returned is equal to the one supplied to the authorization endpoint.
[REDIRECT_URI]?code=[AUTHORIZATION_CODE]&state=[STATE]
4. Your application uses this authorization data to gain access to the account.
Using the data you received in the last step you can call the token endpoint and get an access token and a refresh token that can be used in the following communication.
POST /oauth/token HTTP/1.1
Host: api.nibeuplink.com
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
grant_type=authorization_code&client_id=[CLIENT_ID]&client_secret=[CLIENT_SECRET]&code=[AUTHORIZATION_CODE]&redirect_uri=[REDIRECT_URI]&scope=[SCOPES]
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"access_token":[ACCESS_TOKEN],
"expires_in":300,
"refresh_token":[REFRESH_TOKEN],
"scope":[SCOPES],
"token_type":"bearer"
}
5. Authenticate the subsequent requests.
Once the access token has been retrieved it can be used immediately and until the expires_in seconds has passed to access resources in the NIBE Uplink API. To access token needs to be provided as a bearer token to the API endpoints.
GET /api/v1/systems HTTP/1.1
Host: api.nibeuplink.com
Authorization: Bearer [ACCESS_TOKEN]
Example: Refresh Token
Once the access token has been retrieved it can be used immediately and until the expires_in seconds has passed. After that the access token has to be renewed and this can be done using the refresh_token (only available in the Authorization Code Grant flow). This is done by calling the token endpoint with the refresh token.
POST /oauth/token HTTP/1.1
Host: api.nibeuplink.com
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
grant_type=refresh_token&client_id=[CLIENT_ID]&client_secret=[CLIENT_SECRET]&refresh_token=[REFRESH_TOKEN]
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"access_token":[ACCESS_TOKEN],
"expires_in":300,
"refresh_token":[REFRESH_TOKEN],
}