Headless flow
This guide shows you how to set up headless authentication for Norwegian BankID. This means that you can provide your own user interface within your app or website.
The headless flow supports the Safe Conversation (Call centre) authentication type.
For an introduction to the Safe Conversation feature, see the About page.
Prerequisites
- Follow the steps on the Initial preparations page to establish a connection with Norwegian BankID.
-
Before you can start making requests to the Authentication REST API, you need to learn how to connect to it. To do this, see Connect to Signicat APIs Quick start guide.
Ensure that you set the Authentication REST API permission for your API client. When you have obtained an access token and are ready to make an API request, return here to resume this guide.
Learn more about the Signicat Authentication REST API- Authentication REST API for conceptual documentation.
- API Reference for endpoint descriptions.
1. Build the authentication request (Create a new session)
This section describes how to make an HTTP POST request to the /sessions endpoint, to create a new session and start an authentication.
To begin the authentication flow, your application must first start a session by utilising the /sessions endpoint. The endpoint automatically creates a session when you send a request. The flow and resulting information from the transaction depends on the parameters you pass in the body.
The response from the headless authentication request returns the necessary data directly in the idpData object, which you use to drive the authentication in your own custom user interface.
To create a new session, send a POST request to https://api.signicat.com/auth/rest/sessions?signicat-accountId={accountId}.
You can find your accountId in the Signicat Dashboard.
The following sub-sections show examples and descriptions of attributes that you can include in the request.
Request example
Here is an example authentication request for creating a new Safe Conversation session:
{
"allowedProviders": ["nbid"],
"flow": "headless",
"additionalParameters": {
"nbid_auth_type": "PHONE"
},
"requestedAttributes": [
"name",
"firstName",
"lastName",
"nin",
"dateOfBirth"
],
"prefilledInput": {
"nin": "17029012345"
}
}
If the authentication completes successfully, then the final result contains the attributes that were requested.
Attributes are described in more detail in the following sections.
Initialise authentication
To initialise a headless authentication with Norwegian BankID, you must specify the following required fields in the initial request:
For more detailed field descriptions, see the API reference.
Control the user flow (additionalParameters)
You use additionalParameters to control the headless flow:
Prefill user information (prefilledInput)
When using the Safe Conversation feature in the headless flow, you must prefill the nin (national identity number) of the user, otherwise the transaction will fail.
"prefilledInput": {"nin": "17029012345"}
For conceptual documentation about prefilling, see the eID and Wallet Hub guide > Prefilling user information.
User information (requestedAttributes)
You can request the following user information in the requestedAttributes object:
Response example
Here is a response example from the "Create a session" request for the Safe Conversation authentication type:
{
"id": "425cbb48--...",
"accountId": "a-sdge-...",
"status": "CREATED",
"idpData": {
"bindingMessage": "Snedig redning"
},
"allowedProviders": [
"nbid"
],
"flow": "headless",
"requestedAttributes": [
"dateOfBirth",
"firstName",
"lastName",
"name",
"nin",
"idpId"
],
"sessionLifetime": 1200,
"expiresAt": "2026-06-29T11:08:34.9495067+00:00"
}
The CREATED status means the end-user has not started to authenticate yet. The response also contains an idpData field, which contains necessary input data for your frontend, here to use the bindingMessage.
The Safe Conversation user flow
To implement the Safe Conversation flow logically in your call centre interface, the sequence of events should be:
- Collect national identity number: Before creating the new session, the support agent validates the caller and collects their national identity number (
nin). - Create a new session: Your application creates the session using
ninin theprefilledInputobject. This instantly triggers a push notification to the user's BankID app. - Verify binding message: Show the
bindingMessagein the agent interface. The agent asks the end-user to open their BankID app and confirm they see the same message. - Select binding message: The end-user must select the correct binding message in their BankID app.
- Authenticate: The end-user completes the authentication in their BankID app as they normally do.
See also the high-level description, including screen examples, of the flow on the About page.
2. Obtain user information (Get session status)
Make an HTTP GET request to the /sessions endpoint to poll for information regarding the session and ongoing authentication.
Upon successful authentication, a response is returned that contains the user information requested in the "Create a new session" call carried out earlier.
Request
No data specific for Norwegian BankID needs to be provided in this request.
To get the status of a session, send a GET request to https://api.signicat.com/auth/rest/sessions/{id}.
You can find the id value in the response that was returned when you created the session.
Response
The "Get session status" response contains a status field, which indicates the current status of the session. Below you can see an example response for a successfully completed session for authentication in a Safe Conversation (call centre):
{
"id": "91160261-...",
"accountId": "a-sdge-...",
"status": "SUCCESS",
"provider": "nbid",
"subject": {
"id": "fOthqpBQyuYxNPyuj...",
"idpId": "9578-6000-4-2595757",
"name": "Kari Nordmann",
"firstName": "Kari",
"lastName": "Nordmann",
"dateOfBirth": "1990-02-17",
"nin": {
"value": "17029012345",
"issuingCountry": "NO",
"type": "BIRTH"
}
},
"loa": "substantial",
"allowedProviders": [
"nbid"
],
"flow": "headless",
"requestedAttributes": [
"dateOfBirth",
"firstName",
"lastName",
"name",
"nin",
"idpId"
],
"sessionLifetime": 1200,
"expiresAt": "2026-06-29T14:54:14.9449404+00:00"
}
Status overview
In the session responses you will get a top level status in the status field.
What you need to do with the response
Depending on the top level status you receive in the response, you need to handle the response a bit differently:
- For
CREATEDstatus you want to read thebindingMessageand handle the response accordingly. - For
SUCCESSstatus you will find the authentication result in thesubjectfield. - For
ABORTstatus you can assume that the end-user intentionally cancelled the transaction. - For
ERRORstatus you can check theerror.codefield to see what kind of error occurred. - For
CANCELLEDstatus you or the end-user has cancelled the transaction.
We recommend that you poll for status every 1 to 3 seconds until the value for status is either SUCCESS, ABORT, or ERROR, at which point the session is finalized.
Cancel a session (optional)
You can stop an ongoing authentication session by using the Cancel flow endpoint.
This is useful if you want to:
- Provide a way for your end-users to cancel the transaction, both at Signicat and Norwegian BankID (via a link/button). It is especially useful if you lock the transaction to a particular national identity number.
- Cancel an ongoing transaction for a particular national identity number before starting a new transaction for the same person.
A successful cancellation returns 200 OK of type CANCELLED.
Example response
{
"id": "3d07c219-0a88-45be-9cfc-91e9d095a1e9",
"accountId": "string",
"status": "CANCELLED",
"provider": "nbid",
...
}
Next steps
Dive deeper into Authentication REST API and improve your application with advanced security features: