ZignSec

About the Browser-based APIs

APIs are normally GUI-less, on the back-end and server-to-server. ZignSec however introduces Browser-based APIs for running workflows requiring user interaction, for example the eID login processes.

A Comparison of Browser-based and Backend API

  • Browser-based API example: The Nordic BankIDs can all be run on the Browser-based API. This is the choice for HTML-based front-ends and needs a browser window to run the neccessary user interactions.
  • Backend (server-2-server) API example: ZignSec has implemented the “BankID API for Apps” which is better suited for backend integrations without user-interactions – for example when building mobile apps.

Browser-based API´s Call Sequence

Overview:

  1. Make Initiation Call <- Returns a start-url.
  2. Start Browser-based workflow with start-url
  3. Poll or Wait for a signal that workflow is completed (with desired approach).
  4. Retrieve results, that is the Identity object of the logged in person.

In detail:

  1. Request a Session Token (aka RequestId) also specify the operation. You will be returned a new unique RequestId session token from Zignsec used throughout the process to identify your session and results, as well as a redirect_url containing the same session token, that will start the browser workflow.
  2. Run the browser workflow, that is, navigate the redirect_url. This will also, on the server, setup and initiate a parallel remote BankID session, or similar for the requested login service.
    (step 2.5, here the user Logs in or Signs in the browser window and/or other external utilities, like the Danish key card, or the Swedish BankID app…)
  3. Retrieve the results in either of these ways:
    1. Wait until the browser is redirected to the Target url, which signals that the eID process is completed and you should issue a GET to fetch the results.
    2. Set up success and error webhooks to have the results pushed to you automatically.
    3. Issue a GET repeatedly to poll for status changes until you have the final results in the response body.

Note: We recommend you set the target parameter to a redirect-url called upon completion (successful or failed). In this way you avoid polling with GET method, target is navigated to automatically via a HTTP redirect after the last step in the Authenticate or Sign process. Also, we recommend you use an Html IFrame as a GUI container in the browser for the web-based workflow.

Result Retrieval on Browser-based API

  • Callback, also known as Push-delivery, is set up by either:
    1. Set the Target url parameter in the init call and let that navigation trigger a GET for result retrieval.
    2. Register a webhook callback url where final results will be delivered. Webhooks need to be registered per customer in contact with ZignSec.
  • Polling is done by periodically issuing a GET until it returns the results. Recommended interval is every two seconds.

Caution: Polling puts an extra load on the system and network resources. This is quite relevant for the Norwegian BankID which incorporates a more state-ful web server back-end. Polling also means a more complicated integration since you need a separate task to periodically check for result updates.