CKW OpenEnergy Client API
home
OpenEnergy API
Introduction
The OpenEnergy API enables CKW customers with smart meters installed at their homes to access their energy consumption and production data. By utilizing this API, customers can conveniently retrieve their energy metrics through various means, such as the CKW web portal or an Android/iOS app. For detailed information about data access, please visit the CKW Website. This API is designed to make meter data easily accessible for integration into websites and applications.
There are two apis to consume Smartmeter data but fulfill different use cases. First use case is, when data is requested directly by the client. In the second use case the data is consumed by a backend from the application. Whenever possible the data should be consumed directly from the client.
In both cases CKW Single Sign On is used for user authentication. The Main difference between the apis is in the authentication on the api. When the api is called directly from the client, the jwt token is used for authentication on the api. For use cases that use a backend specific app credentials will be generated, since the jwt token is only available in the client.
Test Consuption Console URL
https://e-customer-smartmeter.de-c1.eu1.cloudhub.io/console/
Availability of Data
While CKW offers its own dedicated app for accessing meter data, the API is open to any app that supports CKW Single Sign On. This means that customers have the flexibility to choose third-party apps or extract their data through the API for seamless integration into other systems.
CKW Single Sign On
To request data from the API, users need to have an account for CKW Single Sign On. CKW Single Sign On instances are implemented using Keycloak, ensuring secure authentication and authorization processes. Oauth2 is used for authentication which uses short-lived jwt tokens. The application has to request a new token after expiry of the old one.
Developers that want to create applications that use this api, can request a client for Keycloak on the CKW Website (see link in introduction). After the Client creation the developer will be notified. The client details, which are required for the sso login process, will be attached.
Keycloak Documentation Page:
https://www.keycloak.org/docs/latest/securing_apps/
production config: https://idp.ckw.ch/auth/realms/CKW/.well-known/openid-configuration
test config: https://idp-int.ckw.ch/auth/realms/CKW/.well-known/openid-configuration
Login
Application should redirect to Keycloak Login Page when a user is not logged in. Redirect Back to the App should be handled by keycloak if correct redirect Page is passed in the login request.
URL to Login Page:
Where client_id and redirect_uri has to be passed by the Application and state, response_mode and nonce is normally handled by OAuth2 libraries.
Fetch Authorization Token:
POST
https://$IDP_URL/auth/realms/CKW/protocol/openid-connect/token
Body (x-www-form-urlencoded)
code:$code
grant_type:authorization_code (grant type password is not supported)
client:$client_name
redirect_uri:$uri
$code is delivered from keycloak from valid Login Redirect.
Refresh Authorization Token:
POST
https://$IDP_URL/auth/realms/CKW/protocol/openid-connect/token
Body (x-www-form-urlencoded)
refresh_token:$refresh_token
grant_type:refresh_token
client:$client_name
$refresh_token is part of the Authorization Token Response.
API
Endpoints
The api provides two main endpoints one for core data and another for meter data. For detailed information about each endpoint, please refer to the specification.
Versioning
Versioning in the api is archieved with the major version in the endpoint url. Breaking changes as removing or renaming fields will be done in a new major version. Completely new fields might also be added in the same major version.
Rate Limiting
The API implements rate limiting per user. The api exposes rate limiting headers, these start with 'x-ratelimit'. With these headers the app knows how many requests in a given time might still be sent. More information about the headers can be found in the speficiation section.
Support
If you need support, please send us a mail to openenergy@ckw.ch