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
- Make Initiation Call <- Returns a start-url.
- Start Browser-based workflow with start-url
- Poll or Wait for a signal that workflow is completed (with desired approach).
- Retrieve results, that is the Identity object of the logged in person.
- 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.
- 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…)
- Retrieve the results in either of these ways:
- 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.
- Set up success and error webhooks to have the results pushed to you automatically.
- 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:
- Set the Target url parameter in the init call and let that navigation trigger a GET for result retrieval.
- 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.