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

Integration guide for Auðkennisappið

Have you tried it out in sandbox?

We recommend that you test our services with your sandbox account before implementing them in production.

Prerequisites​

Before you can create a production account, you need to configure Auðkennisappið access with an onboarding manager. To get help with this, please contact us.

Create a production account in the Dashboard​

Once you have received the needed permissions, you can create the account from the Signicat Dashboard:

For the complete documentation index, see llms.txt

  1. Go to Signicat Dashboard > Organisation.
  2. Click the + Add account button.
  3. Under Account Name, enter the name of your account.
  4. Tick the Production account box.
  5. Click the Create button to create the new account.

Add eID to the Dashboard​

For the complete documentation index, see llms.txt

  1. In the Signicat Dashboard, navigate to Products > eID and Wallet Hub > eIDs.
  2. Click + Add new in the top right.
  3. Choose the eID from the list. Then, fill in any required configuration and click Add.
  4. Now, review that the eID is available and displayed as Enabled in the eIDs page.

Set up a connection with a protocol​

To establish a connection between Auðkennisappið and your application, you need to use a standard authentication protocol.

For the complete documentation index, see llms.txt

Supported authentication protocols

Signicat supports the standard OpenID Connect (OIDC) and SAML 2.0 protocols. In addition, we offer our bespoke Signicat Authentication REST API.

The protocol you choose depends on your goals and preferences. The Authentication REST API provides flexibility and an easy setup. Otherwise, we recommend OIDC, since SAML 2.0 is much more complex to implement and usually requires a federation agent. OIDC is an industry standard with managed user sessions, unlike the Authentication REST API.

To learn more about these authentication protocols, see the Signicat eID and Wallet Hub documentation.

Choose your integration flow​

You can choose between the following integration flows and authentication protocols for Auðkennisappið:

For the complete documentation index, see llms.txt

Redirect flow​

With the redirect flow, you simply initiate a session using one of the supported protocols, and redirect the end-user to the provided redirect URL/URI.

For step-by-step instructions per authentication protocol, see the eID and Wallet Hub Quick start guide > Build a connection.

For information about how to set up the redirect flow with the Signicat Authentication REST API, see the Redirect flow guide.

Headless flow​

If you want complete control over the user experience, you can use the headless flow in the Signicat Authentication REST API. For a general overview of the headless flow, see the Headless flow guide.

How it works​

In a headless flow, the user interacts with Auðkennisappið through one of these methods:

  • QR code flow: Scanning a dynamic QR code (cross-device)
  • App2App and Web2App flows: Clicking a link (same-device)
  • Notification flow: Receiving a push notification

You can determine the flow by providing the appropriate parameters in your authentication request. You also need to design your application to handle the respective flow requirements.

Prerequisites​

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. Create a new session​

To create a new session and start an authentication flow, send a POST request to the /sessions endpoint.

Here are some request examples for different authentication types:

{
  "allowedProviders": ["audkenni-app"],
  "flow": "headless",
  "requestedAttributes": [
    "name",
    "firstName",
    "lastName",
    "dateOfBirth",
    "nin",
    "age"
  ],
  "additionalParameters": {
    "authType": "qr"
  }
}
User-initiated flow

In the QR code flow, the end-user initiates the authentication:

  1. You create the session and generate a QR code (from the deviceLink you receive in the response).
  2. The end-user opens the Auðkennisappið app on their mobile device and scans the code.

Because the end-user identifies themselves when scanning the QR code, you do not need to provide prefilledInput (such as nin) in this request.

Key parameters​

To initialise a headless authentication with Auðkennisappið, you need to specify the following required fields in the initial request:

For more detailed field descriptions, see the API reference.

You can further configure your authentication process by specifying the following parameters:

additionalParameters​

Use additionalParameters to control the headless authentication behaviour:

Country code

Because Auðkennisappið operates only in Iceland, you do not need to specify a country parameter. The country code is automatically set to is.

prefilledInput​

notification requires prefilled nin

When using the notification authentication type, you must provide the nin (national identity number) of the user, otherwise the transaction will fail.

Example with prefilled nin:

"prefilledInput": {
  "nin": "1702901234"
}

For conceptual documentation about prefilling, see the Prefilling user information guide in the eID and Wallet Hub documentation.

requestedAttributes​

You can request the following user information in the requestedAttributes object:

For the complete documentation index, see llms.txt

Response example​

Depending on the authType, the API returns different properties in idpData:

For qr, web2app, and app2app, the response contains a deviceLink:

{
    "id": "425cbb48-4f8e-9d21-a3597b6f2814",
    "accountId": "a-sdge-...",
    "status": "CREATED",
    "idpData": {
        "deviceLink": "https://test.audkenniapp.is/device-link?deviceLinkType=Web2App&sessionToken=..."
   },
    "allowedProviders": [
        "audkenni-app"
    ],
    "flow": "headless",
    "requestedAttributes": [
        "dateOfBirth",
        "firstName",
        "lastName",
        "name",
        "nin",
        "age"
    ],
    "sessionLifetime": 1200,
    "expiresAt": "2026-06-29T11:08:34.9495067+00:00"
}

Here is how you can serve the device link to your end-users:

  • qr: Render the deviceLink as a QR code image for the end-user to scan.
  • web2app / app2app: Render a button or link with the deviceLink to trigger the app switch.
Response properties​

For the complete documentation index, see llms.txt

Note the following properties in the response object:

  • status: CREATED indicates that the session has been created but the end-user has not started to authenticate yet.
  • idpData: The flow link or code to drive the authentication in your own custom user interface, as shown in the table below:

2. Obtain user information (Get session status)​

For the complete documentation index, see llms.txt

To poll information regarding the status of an ongoing authentication session, you need to send a GET request to https://api.signicat.com/auth/rest/sessions/{id}. You can obtain the id value from the response you received upon creating the session. For more information about the request, see the Get session status endpoint description.

Upon successful authentication, you receive a response containing the user information requested when you initiated the authentication session.

Polling intervals
  • For qr: Poll the status endpoint every 2 to 3 seconds. Auðkennisappið dynamic QR codes require updating the QR code image if updated links are returned.
  • For notification: Poll the status endpoint every 2 to 3 seconds until the session completes.

Request​

To retrieve the status of an ongoing session, you need to send a GET request to https://api.signicat.com/auth/rest/sessions/{id}. You can obtain the id value from the response you received upon creating the session.

In the response example above, the id is 425cbb48-4f8e-9d21-a3597b6f2814 so the request would be:

GET https://api.signicat.com/auth/rest/sessions/425cbb48-4f8e-9d21-a3597b6f2814 HTTP/1.1
Authorization: Bearer <ACCESS_TOKEN>
Accept: application/json
Completing Web2App and App2App flows with userChallengeVerifier

When using web2app or app2app, the Auðkennisappið app redirects back to your callbackUrl with a userChallengeVerifier query parameter, which is Base64URL encoded.

Pass this value as a query parameter in your GET request to the session status endpoint:

GET https://api.signicat.com/auth/rest/sessions/425cbb48-4f8e-9d21-a3597b6f2814?userChallengeVerifier=<USER_CHALLENGE_VERIFIER> HTTP/1.1
Authorization: Bearer <ACCESS_TOKEN>
Accept: application/json

For more information about the request, see the Get session status endpoint description.

Response​

Once the user completes authentication, the session status transitions to SUCCESS with the requested attributes:

{
  "id": "425cbb48-4f8e-9d21-a3597b6f2814",
  "accountId": "a-sdge-...",
  "status": "SUCCESS",
  "provider": "audkenni-app",
  "subject": {
      "id": "xAqEBBlTUbXYWHjLp3-...",
      "name": "ANNA TOMASDOTTIR",
      "firstName": "ANNA",
      "lastName": "TOMASDOTTIR",
      "dateOfBirth": "1990-02-17",
      "nin": {
          "value": "1702901234",
          "issuingCountry": "IS",
          "type": "CIVIL"
      },
      "age": "36"
  },
  "loa": "high",
  "allowedProviders": [
      "audkenni-app"
  ],
  "language": "is",
  "flow": "headless",
  "requestedAttributes": [
      "age",
      "dateOfBirth",
      "firstName",
      "lastName",
      "name",
      "nin"
  ],
  "sessionLifetime": 1200,
  "expiresAt": "2026-07-03T07:19:28.6439001+00:00"
}

Next steps​

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
On this page