Kit Configuration

Learn how Bright Kit is configured to enable Bright Energy to make requests.

Authorization

Authorization for Kit is dependent on several factors. As this is your integration built for use by Bright Energy, architecture, User country and security restrictions will all play a factor in deciding the authorization methods enabled.

There are two groups of authorization methods:

  • User Authorization
  • Data Layer Authorization

User Authorization

BankId (Sweden)

In Sweden the most well known login eID solution is BankId.

BankID is a common way to identify yourself in digital environments. You do not have to create accounts with passwords with different actors, and can instead use the same secure solution for everyone. Like showing your ID, but digitally.

In order for your end-users to trust the application and login securely, we relay all BankId API calls to your backend so the end-user will see your company name and certificate in the BankId app.

Test BankId

If you do not have a BankId for personal use already, please obtain a test bankId from: https://developers.bankid.com/test-portal/bankid-for-test

Afterwards you can test if it works at: https://test.bankid.com/

Get a BankId certificate

You must order a BankId certificate from one of the approved banks found at: https://www.bankid.com/en/foretag/kontakt-foeretag.

OpenId

OpenID is an easy and safe way for people to reuse an existing account and user profile from an identity provider, for example Apple, Google, or Microsoft to login to any OpenID-enabled applications and websites without creating a new registration and password. You choose the provider, such as Google and enter your Gmail address and password to login.

Requirements

  • You must expose your.well-known/openid-configurationfor Bright Energy to read.
  • client_Id, client_secret and scope needs to be sent to your Customer Success Manager in a secure manner.
  • You need to configure the following callbackUrl's:
Callback URL'sPurpose
https://my-organisation-name.production.getbright.se/v3/auth/my-organisation-name/callbackProduction callback URL
https://my-organisation-name.staging.getbright.se/v3/auth/my-organisation-name/callbackStaging callback URL
https://mypagesURL/auth/my-organisation-name/callbackMy Pages Production callback URL
https://mypages.my-organisation-name.staging.getbright.se/v3/auth/my-organisation-name/callbackMy Pages Production callback URL

📘

Only if you have a My Pages setup do you need My Pages callback URLs.

Learn more at: https://openid.net/developers/how-connect-works/

openId endpoints

The endpoints in openId are provided as examples so you can test your OpenID setup with Bright Kit. Please build your OpenID integration to the specification: https://swagger.io/docs/specification/v3_0/authentication/openid-connect-discovery/.

If you do not have an OpenId solution provider today, we recommend Signicat .

Signicat

Signicat is an all-in-one solution for using the country specific eID for your Users login. Read more at: Signicat Developer Hub to see what methods are included in each country and how to get started with your own Signicat account.

One-time code via email

If some of your Users cannot login with bankId we can enable an email login using a single use verification code. Please note that users should be uniquely identified with their email address and have access to a single Account only.

Data Layer Authorization

Bright Energy requires access to your entire data layer at any time regardless user interactions. This is due to the requirement to implement the Data Synchronisation for an optimal User experience.

API Key

The simplest method to implement is an apiKey header.

The API key must be environment specific, generated by the Organisation and able to be revoked and replaced in the event of a security exposure.

The header name can be anything, for example Ocp-Apim-Subscription-Keyand the correct value.

Bearer: Access Token

Using the Authorization header in combination with a valid access_token generated from oauth or openId. It is possible to use a pre-generated JWT token that never expires, similar to an apiKey, but we recommend an oauth implementation to increase security.

IP Whitelist

Please whitelist the following IP addresses if required for accessing your Bright Kit.

  • 46.254.9.239 (Cleura staging)
  • 46.254.9.177 (Cleura production)
  • 79.136.34.34 (Office VPN)
  • 86.107.49.69 (Forward Proxy for all environments)

Variables

  • stagingis the name of the environment Bright Energy will target when making requests.
  • domainis the name of the domain you have deployed the Bright Kit implementation to.
  • v1is the version of the Bright Kit being targeted.
    • v1

Dates and Timestamps

Date Formats

All dates shall be strings formatted according to the ISO 8601 standard, including timezone definition:

  • 2024-10-10T09:59:44+02:00

  • 2024-10-10T09:59:44Z

Time Periods

Time periods are always set between a fromDate and a toDate as query parameters in the request. The resolution parameter is used to structure the response data for graphs viewed in that resolution.

  • fromDate is always required. If requesting real time data use this field only.

  • toDate is sometimes required.

  • resolution is sometimes included in the request.

Responses for time period requests

Response bodies shall always include a startDate and endDate to detail the time period of the data. In cases where you cannot supply the same time period as requested, provide startDate and endDate fields that match the response data.

Order of time series results

Responses which include values related to a startDateand endDate the data series should be returned chronologically. Do not send randomized results.

HTTP Response Status Codes

Implemented endpoints shall return the specified response status codes.
Any endpoint that is not implemented shall return the code 501 Not Implemented.

WebViews

What is a WebView?

A WebView is a web browser that is embedded within an app.

Configuration

Before Bright Energy can make a Get WebView url request you will need to send us a list of WebViews you would like to be available in the app.

Each item in the list should include:
- View Name
- urlKey (camelCasedKeyName)
- Value (camelCasedKeyValue or full URL string)
- App location for the WebView to be available to users
- openInBrowser (boolean)(set to true to open in external Browser App instead)

WebView Flows:

Shared View:

User Specific View:

  • Bright Energy stores the name of the urlKey and uses it to make a Get WebView url request
  • termsAndConditions -> termsAndConditions
  • We request Get WebView url with all the query parameters (userid, locationid etc...)
  • The Organisation computes a finalUrl and responds to the Get WebView url request
  • Bright Energy renders this finalUrl as a WebView in the app.

Example:

WebViews can be used for opening webpages for user actions not currently supported by the app such as the renewal of an agreement.

You have previously given us a view name called Account Renewal with the urlKey accountRenewal to be located inline with existing agreements for the account.

Bright Energy will then request your Get WebView url endpoint with the following structure:

https://{kitEnvironment}.{kitDomain}/{kitBasePath}/webview?accountid={accountId}&clientId=app&language=sv&urlkey=accountRenewal&serviceId={serviceId}&userId={userId}.

Your response body has the computed finalUrl set as the value of the body parameter with key url. The finalUrl should include everything needed to load the WebView (authentication, tracking, etc...) so that Bright Energy can successfully render the WebView for the user.