How to integrate with eID Hub
Overview
- Request an API token
- Get test users and try the demo application
- Implement your API integration
- 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:
-
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
andBelgian 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
, andFreja
, which do not provide a UI, you can either use the eID Hub frontend or implement your own UI.For
Onfido
,Swisscom
andDanish 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.
-
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)
-
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 thesign
andnoBankID
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 benull
.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.