User registration

The user registration flow in NET2GRID Insight has 3 steps:

1. End user gets created by customer via the B2B Account Management API (provisioned)
2. End user activates their account through the app and is able to authenticate (registered)
3. Measurement data received for end user (active)

In this guide we will describe every step of the user registration flow and how the CE API endpoints should be used by the app.

Provision end users

NET2GRID Insight Platform expects that the end-user account will be created via the B2B Account Management API by the customer. The details about the information that should be provided will not be analysed as part of this guide but we will mention the items that will be of interest in the registration flow. The parameters during end-user account creation that are relevant to the registration process are:

• Email address: This email address will be used to authenticate the user via username/password and will be used upon email verification to proceed with the account activation
• create_verified_user flag: This flag is set during the end-user account registration and controls if the email verification will be a prerequisite for the end user to set their password and activate their account
• Firstname and Lastname: These fields will be an extra validation step to allow the end-user to proceed with registration through the app in case the email verification is required.
• External Authentication Provider Id: This field is relevant only for users that will use Single Sign On (SSO) authentication process and should match the end user identifier that the External Authentication Provider of the customer knows.
• voucher_code in Order Information block: This field is relevant only for customers that want to use a specific identifier (eg a promo code) that will allow their end users to activate their account.

Register account for end user

NET2GRID Insight Platform supports 2 types of authentication for an end user:

1. Authenticate through username and password
2. Authenticate with Single Sign On (SSO) via an external authentication provider

Below we will discuss the endpoints that should be used for each process separately

Registering end-users with username/password authentication

The flow that should be followed when the end user will be authenticating through

For an end user to be activated in the NET2GRID Insight it is a prerequisite that the customer provisions the end user first. After that, the deciding factor of how to proceed is if the user needs to verify their email or not to proceed with the registration. In case the email verification is not required or has been verified based on the email verification steps described below the app should proceed with letting the end user specify their password.

CE API provides the following endpoint to allow end users to set their password:

POST /v2/registration/no-gateway
No authorization required

The request body should contain the email address and the password that should be set for the end user to authenticate like:

{
 "email_address": "<email>",
 "pincode": "<password>"
}

For the call to be successful it is required that:

• the email address is known to NET2GRID Insight Platform - has been provisioned
• there is not an end user account activated already with the provided email
• the pincode provided meets the criteria for the password policy that applies to the platform
• if voucher_code has been defined for the end user (see provision section for details) then the request contains also the voucher_code field that should match the provisioned voucher_code like the example below:
  JSON

  {
   "email_address": "<email>",
   "pincode": "<password>",
   "voucher_code": "<voucher_code>"
  }
  

📘

Password Policies

The password policy that will apply to all end user is agreed upon customer registration. The most common password policies that are used for end users are:

• Pincode
  • 6 characters
  • Contain only numeric characters
• Password
  • 6-16 characters
  • Can contain numbers
  • Can contain special characters _ ! " ( ) = [ ] { } ? + * ~ # , ; . -
  • Can contain uppercase/lowercase latin letters (a-zA-Z)
  • German characters are not allowed.

Full documentation of the above call can be found here.

After a successful execution of this endpoint the end user should be able to get a token that will be used for their authentication in all the relevant CE API endpoints.

Email verification

Email verification is a process that is recommended to be used for security reasons especially in cases where the email address of the end user has not been verified by the customer before provisioning the end user in NET2GRID Insight Platform.

🚧

When the customer specifies during end user provisioning that the email verification is not required, NET2GRID trusts that the email address and PII information provided is valid and truthful.

The email verification is initiated by the following CE API endpoint:

POST /v2/registration/provision
No authorization required

An example screen from Ynni app on this step is available below:

The body of the response should look like the following:

{
  "first_name": "<firstname>",
  "last_name": "<lastname>",
  "email_address": "<email>",
  "labelpartner": "<labelpartner name>",
  "imported": "true"
}

where

• first_name, last_name and email_address should match a provisioned end user in NET2GRID Insight Platform that has not been activated yet
• labelpartner should match the name of the labelpartner that has been defined for the end user when provisioning. The applicable names for labelpartners will be provided by NET2GRD during customer onboarding
• imported flag should be set to true

A successful execution of the call should return a successful response

{
  "status": "ok",
  "message": "ok"
}

and will result in an email being sent to the provided email address. On Ynni app this is visible to the end user via a relative screen:

The email will contain a link that when pressed the verification will be considered successful. On Ynni app the email will look like the following:

📘

Deep linking setup

It is recommended that deep linking has been setup on Insight so that the app opens directly when the link is pressed. In this case the app should trigger the Verify User CE API endpoint. Please contact NET2GRID for further instructions.

Registering end-users using Single Sign On (SSO) with external authentication provider

The flow that should be followed to register an end user that will login via SSO is described in the flow below:

The prerequisites that need to be covered for an end-user to be registered and authenticated using SSO are:

1. The "external_authentication_provider_id" to have been properly specified while provisioning the account of the end user via Account Management API
2. The customer's IDP to have been configured in order to return the "external_authentication_provider_id" in the JSON response of the introspection call (More info in Authentication using single sign-on and token introspection section)