For the complete documentation index, see llms.txt. You can also append .md to any page URL to get its markdown version.
Skip to main content
For the complete documentation index, see llms.txt.

For the complete documentation index, see llms.txt

Redirect flow

This guide shows you how to set up regular BankID authentication (High and Biometric), using the Signicat Authentication REST API with redirect flow.

Prerequisites​

  1. Follow the steps on the Initial preparations page to establish a connection with Norwegian BankID.

  2. For the complete documentation index, see llms.txt

    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

1. Build the authentication request (Create a new session)​

For the complete documentation index, see llms.txt

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 this endpoint contains an authentication URL, to which you can embed in an iframe and present to the end-user to start their transaction.

To create a 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 examples​

Here are two example requests for creating a new session for a Norwegian BankID login for normal authentication and authentication with payment data:

For the complete documentation index, see llms.txt

{
    "allowedProviders": ["nbid"],
    "flow": "redirect",
    "additionalParameters": {
        "nbid_idp": "BID"
    },
    "prefilledInput": {
        "nin": "17029012345"
    },
    "requestedAttributes": [
        "dateOfBirth",
        "firstName",
        "lastName",
        "name",
        "nin"
    ],
    "callbackUrls": {
        "success": "https://example.com/success",
        "abort": "https://example.com/abort",
        "error": "https://example.com/error"
    }
}

Upon sending this request, the Norwegian BankID session will start.

If the authentication completes successfully, the final result will contain the attributes that were requested.

Attributes are described in more detail in the following sections.

Initialise authentication​

To initialise an authentication with Norwegian BankID, you can use the following attributes in the initial request:

Control the user flow (additionalParameters)​

You use additionalParameters to control the redirect flow. This is not a required field.

Prefill user information (prefilledInput)​

For the complete documentation index, see llms.txt

You can use the prefilledInput parameter to prefill information about the user, for example, so the user does not have to fill in this information manually. If prefilled, only the user with the prefilled information will be able to authenticate. This is not a required field.

For Norwegian BankID, you can prefill the national identity number, nin:

"prefilledInput": {"nin": "17029012345"}

Payment data (paymentPrefillData)​

For the complete documentation index, see llms.txt

When you want the end-user to approve a payment before the authentication, you set the additional parameter nbid_auth_type to PAYMENT (as shown shown in the examples above), and you must prefill data about the payment in the paymentPrefillData object.

Mandatory

The paymentPrefillData object is mandatory for payment.

Here is an example of a complete paymentPrefillData object:

{...},
"paymentPrefillData": {
        "reference": "composite-payment-1234",
        "payments": [
            {
                "reference": "individual-payment-56",
                "amount": "100",
                "currency": "NOK",
                "receiver": "ACME AS"
            },
                  {
                "reference": "individual-payment-78",
                "amount": "200",
                "currency": "NOK",
                "receiver": "ACME AS"
            }
        ]
    }

These are the mandatory attributes inside the paymentPrefillData object:

User attributes (requestedAttributes)​

You can request the following attributes from users of Norwegian BankID.

For the complete documentation index, see llms.txt

Response examples​

Here are two response examples from the "Create a session" response for normal authentication and authentication with payment data:

For the complete documentation index, see llms.txt

{
    "id": "fb432801-...",
    "accountId": "a-sdge-...",
    "authenticationUrl": "https://<YOUR_SIGNICAT_DOMAIN>/broker/sp/external-service/login?messageId=21b064c3-28b...",
    "status": "CREATED",
    "callbackUrls": {
        "success": "https://example.com:443/?sessionId=fb432801-66f6-6141-9835-e2a3b42e2e35",
        "abort": "https://example.com:443/abort?sessionId=fb432801-66f6-6141-9835-e2a3b42e2e35",
        "error": "https://example.com:443/error?sessionId=fb432801-66f6-6141-9835-e2a3b42e2e35"
    },
    "allowedProviders": [
        "nbid"
    ],
    "flow": "redirect",
    "requestedAttributes": [
        "dateOfBirth",
        "firstName",
        "lastName",
        "name",
        "nin"
    ],
    "sessionLifetime": 600
}

What you need to do with the response​

You must redirect the end-user to the authenticationUrl found in the response. This is a unique URL which allows the user to perform the Norwegian BankID authentication in context of the session you just created.

End-user authentication​

The end-user follows these steps:

  1. On your website/application, the end-user clicks on a button to authenticate with BankID. Your application sends a request to start an authentication with BankID, as described in the previous section.
  2. The end-user is redirected to the BankID login page.
  3. The end-user logs in using their BankID credentials (this step may involve two-factor authentication).

After the end-user approves the request, the browser is redirected back to the relevant callbackUrl specified in the "Create a new session" request.

For screen examples, see About Norwegian BankID.

2. Obtain user information (Get session status)​

For the complete documentation index, see llms.txt

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.

For the complete documentation index, see llms.txt

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 example​

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 normal authentication and authentication with payment data:

For the complete documentation index, see llms.txt

{
    "id": "fb432801-...",
    "accountId": "a-sdge-...",
    "authenticationUrl": "https://<YOUR_SIGNICAT_DOMAIN>/broker/sp/external-service/login?messageId=21b064c3-28b...",
    "status": "SUCCESS",
    "provider": "nbid",
    "subject": {
        "id": "opuc4kyFUWPkfdmfYTzjS89u6ZCWLHWLZfPR5hpBW24=",
        "idpId": "9578-6000-4-1663921",
        "name": "Kari Nordmann",
        "firstName": "Kari",
        "lastName": "Nordmann",
        "dateOfBirth": "1990-02-17",
        "nin": {
            "value": "17029012345",
            "issuingCountry": "NO",
            "type": "BIRTH"
        }
    },
    "callbackUrls": {
        "success": "https://example.com/success?sessionId=58126fb8-c5e2...",
        "abort": "https://example.com/abort?sessionId=58126fb8-c5e2...",
        "error": "https://example.com/error?sessionId=58126fb8-c5e2..."
    },
    "allowedProviders": [
        "nbid"
    ],
    "flow": "redirect",
    "requestedAttributes": [
        "dateOfBirth",
        "firstName",
        "lastName",
        "name",
        "nin"
    ],
    "sessionLifetime": 600
}

Status overview​

For the complete documentation index, see llms.txt

What you need to do with the response​

For the complete documentation index, see llms.txt

If the returned status is SUCCESS, you will find information about the authenticated user in the subject object.

You will also see what identity provider was actually used by checking the provider field. This can be useful if you allowed more than one identity provider when you created the session.

Success

You have now completed an authentication flow with Norwegian BankID.

Next steps​

Learn more about available request and response attributes for Norwegian BankID:

Attributes reference
Look up available attributes for Norwegian BankID

Dive deeper into Authentication REST API and improve your application with advanced security features:

Signicat Authentication REST API
Find out more about available flows in the eID and Wallet Hub documentation
Message level encryption (MLE)
Read more about how to set up encryption
API reference
Look up endpoint and parameter details in the reference guide

For ecommerce customers under certain conditions, it is also possible to embed the BankID page into your own flow:

Embedded flow (advanced)
Embed the BankID login page in an iframe
On this page