Integration guide for Auðkennisappið
We recommend that you test our services with your sandbox account before implementing them in production.
Prerequisites
Before you can integrate with Auðkennisappið in production, you must complete the following basic onboarding steps:
- 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.
- Once you have received the needed permissions, you can create your production account and add the eID to the Signicat Dashboard. See the eID Hub Quick start guide and then return here to resume this guide.
Choose integration flow and protocol
You can choose between the following integration flows and authentication protocols for Auðkennisappið:
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 Hub Quick start guide > Build a connection.
Headless flow
If you want complete control over the user experience, you can use the headless flow in the Signicat Authentication REST API.
Prerequisites
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.
- Authentication REST API for conceptual documentation.
- API Reference for endpoint descriptions.
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:
- QR code
- App2App
- Notification
{
"allowedProviders": ["audkenni-app"],
"flow": "headless",
"requestedAttributes": [
"name",
"firstName",
"lastName",
"dateOfBirth",
"nin",
"age"
],
"prefilledInput": {
"nin": "17029012345"
},
"additionalParameters": {
"authType": "qr"
}
}
{
"allowedProviders": ["audkenni-app"],
"flow": "headless",
"requestedAttributes": ["name", "firstName", "lastName", "dateOfBirth", "nin", "age"],
"additionalParameters": {
"authType": "app2app",
"callbackUrl": "https://local.dokobit.com/callback",
"message": "This is message.",
"confirmationMessage": "This is confirmation message."
},
"language": "is"
}
{
"allowedProviders": ["audkenni-app"],
"flow": "headless",
"requestedAttributes": [
"name",
"firstName",
"lastName",
"dateOfBirth",
"nin",
"age"
],
"prefilledInput": {
"nin": "17029012345"
},
"additionalParameters": {
"authType": "notification",
"country": "is"
}
}
You set up the authentication process with the following parameters:
Initial parameters
To initialise a headless authentication with Audkennisappið, you must specify the following required fields in the initial request:
For more detailed field descriptions, see the API reference.
additionalParameters
You use additionalParameters to control the headless flow:
requestedAttributes
You can request the following user information in the requestedAttributes object:
prefilledInput
When using the notification authentication type in Audkennisappið, you must prefill 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 eID and Wallet Hub guide > Prefilling user information.
Response example
Here is a response example from the "Create a session" request for the headless flow:
{
"id": "425cbb48--...",
"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"
}
The CREATED status means the end-user has not started to authenticate yet.
The response returns the necessary data directly in the idpData object, which you use to drive the authentication in your own custom user interface:
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 Audkennisappið 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 a headless authentication:
{
"id": "9735a799-...",
"accountId": "a-sdge-...",
"status": "SUCCESS",
"provider": "audkenni-app",
"subject": {
"id": "xAqEBBlTUbXYWHjLp3-...",
"name": "ANNA TOMASDOTTIR",
"firstName": "ANNA",
"lastName": "TOMASDOTTIR",
"dateOfBirth": "1990-02-17",
"nin": {
"value": "17029012345",
"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: