How to integrate with eID Hub

Overview

1. Request an API token
2. Get test users and try the demo application
3. Implement your API integration
4. Get your production credentials

Request an API token

First you will need an API token, please contact us and we can issue you an API token, as there is currently no self-service setup.

The API token will be used for accessing the demo application, and developing your integration (more details below, skip ahead if you want to know the details).

We will initially only provide a token for the testbed environment. Once you have a working integration, production credentials can be requested.

Get test users and try the demo application

We have developed a demo application for the eID Hub that lets you explore the authentication and signing providers available, and what parameters they require and accept. This is accessible only on the testbed environment: https://testbed-eid.scrive.com/demo.html

With the demo application, you select the eID provider you want to use (e.g. Swedish BankID, Norwegian BankID, etc.), along with the method (authentication or signing) and enter any required and optional parameters.

Depending on the eID provider you choose, you may need to install a mobile application, create a test user, or use an existing test user. Details are provided in the test users section of the API documentation

The demo application will send you (via a redirect or a pop-up) to the eID Hub application, where you then authenticate or sign using the test account. Once that is complete, you will be redirected back to the demo application, where you will see the resulting JSON of the eID Hub transaction (details of the JSON structure in the API documentation).

The demo application serves to experiment with what should be done programmatically via API calls. Meaning that the parameters selected in the demo application should go into an API request’s body.

Implement your API integration

As linked to previously, the API documentation is available here: https://testbed-eid.scrive.com/documentation/api/v1/

The documentation has a section on “Authentication” explaining how to use the API token. There is also a short guide on the usage of the eID Hub. Finally, also see the video at the end of this guide showing how to expand the definitions in the API documentation.

Additionally you can find a Postman collection in the attachments below.

When writing your integration, consider the following points:

1. Use of the eID Hub frontend

   eID Hub provides a frontend for all eID providers. If you integrate to more than one eID, it’s recommendable that you use eID Hub’s frontend, because it has the same flow for all providers.

   Norwegian BankID, Danish NemID, Finnish FTN, German Verimi, Dutch iDIN and Belgian Itsme, all have their own stand-alone UI. If only integrating to these providers, it’s not necessary to use the eID Hub frontend. For these providers, the eID Hub frontend redirects to or embeds the provider’s own UI.

   For Swedish BankID, SMS OTP, and Freja, which do not provide a UI, you can either use the eID Hub frontend or implement your own UI.

   For Onfido, Swisscom and Danish MitID, which do not provide a hosted stand-alone UI, you have to use the eID Hub frontend.

   If using the eID Hub frontend, you only need to use two API endpoints: one for creating a new transaction and one for retrieving the transaction’s details. If not using the eID Hub frontend, you will need to use one additional endpoint to start transactions.

2. Redirect or pop-up window

   If using the eID Hub frontend, you will need to decide how to use it.

   We strongly suggest using a redirect, as it provides a smooth end-user experience and has the widest compatibility.

   After authentication or signing, the end user is redirected to the URL specified when creating the transaction. The UI behaviour on this URL is defined by the selected strategy:

   • Redirection: next-step page
   • Pop-up window: self-closing script (probably)

3. Define provider parameters

   The API documentation describes the necessary parameters for each provider and contains the JSON body fields for each endpoint.

   You can collapse and expand the branches with provider parameters, for example, in the “Add new transaction” section, you can expand providerParameters, and then further expand the sign and noBankID branches and see all parameters needed to create a new sign transaction with Norwegian BankID.

   You will also see which parameters are mandatory (marked as Required) and which are optional.

   The response JSON body has a similar nested presentation structure. You can also expand the branches in the documentation. The fields marked as required are always present and will never be null. Other fields may be absent or may be null.

   Be sure to read the section on “Versioning” in the documentation as the addition of new JSON fields is considered a non-breaking change.

Important definitions for different eID methods

Norwegian bankID: Please note that according to Norwegian law, only certain organizations have the right to process Norwegian SSN. Hence, in our production environment you'll not receive a SSN back in the completion data. SSN will only be returned if you as an organization has applied for it and been approved to process this (contact us for more information regarding this topic). You may notice that we return the SSN in our test environment and this behavior only occurs in testbed.

Get your production credentials

Once you have a working integration and a valid agreement with Scrive (the agreement includes the terms set by eID providers) you can request production API tokens. Depending on the eID providers you want to use, we may need to apply for customised credentials on your behalf.