Skip to main content

Authentication REST API

This guide details how to set up ID-porten using the Signicat Authentication REST API redirect flow.

Prerequisites​

We assume you have done the following initial preparations:

  1. Follow the steps on the Initial preparations page to establish a connection with ID-porten.

  2. 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

Implement the authentication flow​

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

Here is an example request body for an authentication with ID-porten:

{
    "flow": "redirect",
    "language": "nb",
    "requestedLoa":"substantial",
    "allowedProviders": [
        "idporten"
    ],
    "requestedAttributes": [
        "idportenIdp",
        "idportenLoa",
        "idportenSub",
        "name",
        "nin",
        "idpId"
    ],
    "callbackUrls": {
        "success": "https://example.com/success",
        "abort": "https://example.com/abort",
        "error": "https://example.com/error"
    }
}
Callback URL for abort

You must define callback URL for abort even though ID-porten does not offer any Cancel option for the end-user. If you do not define this callback URL, the session will fail.

Upon sending this request, the ID-porten session will start.

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

Attribute descriptions​

To initialise an authentication with ID-porten, you can use the following attributes in the initial request:

User attributes (requestedAttributes)​

You can request the following attributes from users of ID-porten:

For other field descriptions, see the API Reference.

Response​

Here is an example response after you have created a session:

{
    "id": "9f2af253-292b-4c92-b6b5-271c5cecc6b3",
    "accountId": "a-sdge-9jqN5NhitVnlr7rnZwYE",
    "authenticationUrl": "https://<YOUR_SIGNICAT_DOMAIN>/broker/sp/external-service/login?messageId=1d3bba8b-4ec...",
    "status": "CREATED",
    "callbackUrls": {
       "success": "https://example.com/success",
        "abort": "https://example.com/abort",
        "error": "https://example.com/error"
    },
    "allowedProviders": [
        "idporten"
    ],
    "language": "nb",
    "flow": "redirect",
    "requestedLoa":"substantial",
    "requestedAttributes": [
        "idportenIdp",
        "idportenLoa",
        "idportenSub",
        "name",
        "nin",
        "idpId"
    ],
    "sessionLifetime": 1200,
    "expiresAt": "2026-01-08T09:08:52.0303673+00:00"
}

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 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 the preferred eID. Your application sends a request to start an authentication with the preferred eID, as described in the previous section.
  2. The end-user is redirected to the eID login page.
  3. The end-user logs in using their eID credentials (this step may involve two-factor authentication).

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

For screen examples, see About ID-porten.

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 ID-porten 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 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:

{
    "id": "9f2af253-292b-4c92-b6b5-271c5cecc6b3",
    "accountId": "a-sdge-9jqN5NhitVnlr7rnZwYE",
    "authenticationUrl": "https://<YOUR_SIGNICAT_DOMAIN>/broker/sp/external-service/login?messageId=21b064c3-28b...",
    "status": "SUCCESS",
    "provider": "idporten",
    "subject": {
        "id": "-vMrFZU-H7D1n3NoTugvJT9afALzSTdOEDUXII42Hqw=",
        "idpId": "17029012345",
        "name": "Kari Nordmann",
        "firstName": "Kari",
        "lastName": "Nordmann",
        "nin": {
            "value": "17029012345",
            "issuingCountry": "NO",
            "type": "BIRTH"
        },
        "idportenSub": "oRNX8JRKQ0LfKJpy...",
        "idportenLoa": "idporten-loa-substantial",
        "idportenIdp": "MinID"
    },
    "callbackUrls": {
        "success": "https://example.com/success",
        "abort": "https://example.com/abort",
        "error": "https://example.com/error"
    },
    "environment": {
        "ipAddress": "192.0.2.2",
        "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/143.0.0.0 Safari/537.36"
    },
    "loa": "substantial",
    "allowedProviders": [
        "idporten"
    ],
    "language": "nb",
    "flow": "redirect",
    "requestedAttributes": [
        "idportenIdp",
        "idportenLoa",
        "idportenSub",
        "name",
        "nin",
        "idpId"
    ],
    "sessionLifetime": 1200,
    "expiresAt": "2026-01-08T09:08:52.0303673+00:00"
}
Level of assurance

The loa value in this response, tells you the actual level of assurance of the authentication that took place with the eID that the end-user chose in ID-porten.

Status overview​

What you need to do with the response​

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 ID-porten.

Next steps​

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

Message level encryption (MLE)
Read more about how to set up encryption
API reference
Look up endpoint and parameter details in the reference guide
On this page