Access tokens

In order to grant an application access to the JSON interface (JavaScript Object Notation) or the web user interface of the KOSTAL Smart Energy Meter, the application must authorise itself with the KOSTAL Smart Energy Meter.

Authorisation uses an access token that was previously generated in the KOSTAL Smart Energy Meter.

Creating the access token

Access tokens can be created by going to Profiles > Access tokens.

Clicking on ADD opens a window in which the name, role and expiry date of the access token can be specified.

Parameter

Explanation

Name

Name of the user, application or device that is to use the interface.

Role

  • api: This can be used to query measurement data via the JSON interface.
  • admin: This can be used to log in to the web interface and configure settings. This access token has all the rights that a logged-in user has.

Expires on

Expiry date of the access token.

After creation, the access token is displayed once. It cannot be received or displayed again and should therefore be copied and stored securely upon receipt.

Authorisation of the access token

A newly issued access token must be authorised. By clicking on AUTHORISE, an access token is authenticated and authorised for use of the JSON interface and/or the web user interface.

Deleting the access token

An access token can be deleted from the system by clicking on REVOKE .

 

Using the API access token

Once an API access token has been authenticated and authorised by the user, it can be used by the application for JSON interface requests.

To do this, the access token is transmitted as part of the HTTP header:

GET /api/json/<resource>HTTP/1.1
Host: <energy manager>
Content type: application/json
Authorisation: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9[...]

Using the admin access token

Once an admin access token has been authenticated and authorised by the user, it can be used by the application to display the web user interface.

To do this, the access token is transmitted as part of the HTTP header and/or must be stored in the browser's local memory in order to be read from there.

TTL access token

The life of an access token can be limited during the authentication request. For this purpose, an expiry date is defined in addition to the name of the application. Furthermore, a logged-in user can withdraw an issued access token via the web interface. All subsequent requests made using a withdrawn access token will be rejected.