Skip to main content

Using the Auth API

Two POST requests are needed to authenticate a user:

  • First call /api/auth/start to start the authentication process
  • Then call /api/auth/poll every (pollingInterval * seconds) to check whether the user has authenticated

The /api/auth/start request returns a json object that needs to be used for the second post request to /api/auth/poll

Authenticate each request using Basic Auth. Concatenate your companyKey and apiKey with a colon (companyKey:apiKey), Base64-encode the result, and send it in the Authorization header:

Authorization: Basic <Base64-encoded companyKey:apiKey>

For full details, see the Authentication page.

To log people in with a QR code instead, see Device link (QR) login.

Example request to authenticate a person​

## Request for authentication via e-sim

POST /api/auth/start HTTP/1.1
Host: onboardingdev.taktikal.is
Accept: application/json
Content-Type: application/json
Authorization: Basic <Base64-encoded companyKey:apiKey>
{
"PhoneNumber": "1234567",
"FlowKey": "abc123abc123",
"AuthenticationContextType": "Sim",
"IncludeVerificationCode": true
}

## Request for authentication via app

POST /api/auth/start HTTP/1.1
Host: onboardingdev.taktikal.is
Accept: application/json
Content-Type: application/json
Authorization: Basic <Base64-encoded companyKey:apiKey>
{
"Ssn": "1234567890",
"FlowKey": "abc123abc123",
"AuthenticationContextType": "App"
}

## Response
{
"authRequestId": "1-147rag342352345",
"verificationCode": "1234",
"pollingInterval": 3
}

Parameters​

  • flowKey is a key provided by Taktikal. You can also retrieve a list of your flows via a GET request here /api/management/flow
  • Ssn is the Icelandic social security number of the individual you wish to start the authentication process for
  • PhoneNumber is the mobile number of the individual you wish to start the authentication process for
  • AuthenticationContextType is either Sim or App which decides the authentication method the individual will use to authenticate
  • IncludeVerificationCode (default false) if set to true we will also return a VerificationCode for Sim Auth

Response parameters​

  • verifcationCode which the user will see in their device and we strongly recommend to display on your end. This will be empty for sim auth unless you set the parameter IncludeVerificationCode to true
  • authRequestId is a unique key for this login session, you will need to send with every call to /api/auth/poll (see below) until the user logs in or the request ends (see Expiry and polling window).
  • pollingInterval defines interval between calls to /api/auth/poll in seconds. e.g. if set to 4 you cannot call /api/auth/poll more than once every 4 seconds.

Checking if a user has authenticated

To check if a user has authenticated you need to send a request to /api/auth/poll

Parameters​

  • authRequestId: The unique key for this login session that you received in the call to /api/auth/start
  • flowKey: The same flowkey that was used to call /api/auth/start
  • LookupType: The /api/auth/poll request returns a Customer object but with different amount of information filled out depending on the LookupType. If LookupType.NameAddressFamily is selected then the extra values returned will be returned in Meta

There are three different return types depending on the LookupType

  1. Name: Will only return the SSN and Name of the authenticated person. This has no additional lookup cost. This is the default value if no value is given for LookupType.
  2. NameAddress: Will return Name, SSN, legal address information, citizenship information and gender code. This has an additional lookup cost.
  3. NameAddressFamily: Will return Name, SSN, legal address information, citizenship information, gender code and family information. This has a higher additional lookup cost.

Example request to poll authentication status of user​

## Request for polling

POST /api/auth/poll HTTP/1.1
Host: onboardingdev.taktikal.is
Accept: application/json
Content-Type: application/json
Authorization: Basic <Base64-encoded companyKey:apiKey>
{
"authRequestId": "1-147rag342352345",
"FlowKey": "abc123abc123",
"LookupType": "NameAddress"
}

## Response
{
"waitingForUserInput": false, //true if still waiting for user to authenticate
"statusMessage": "Ok",
"customer": {
"name": "Test User",
"ssn": "1234567890",
"phoneNumber": "1234567",
"address": "Address 5",
"postalCode": "555",
"city": "Gotham City",
"token": "f19b032a237e4fbc94f3",
"flowKey": "abc123abc123",
"meta": {
"GenderCode": "1",
"Citizenship": "IS"
}
}
}

Examples code in different languages​

const axios = require("axios");

const flowKey = "abc123abc123";
const authHeader = { Authorization: `Basic ${Buffer.from("your_companyKey:your_ApiKey").toString("base64")}` };

const start = async () => {
const { data } = await axios.post(
"https://onboardingdev.taktikal.is/api/auth/start",
{
phoneNumber: "1234567",
flowKey,
authenticationContextType: "Sim"
},
{ headers: authHeader }
);

return data;
};

const poll = async (authRequestId) => {
const { data } = await axios.post(
"https://onboardingdev.taktikal.is/api/auth/poll",
{
authRequestId,
flowKey,
lookupType: "Name"
},
{ headers: authHeader }
);

return data;
};

const startAndPollAuthentication = async () => {
const { authRequestId } = await start();

while (true) {
await new Promise((r) => setTimeout(r, 2000));
const { customer, waitingForUserInput } = await poll(authRequestId);
if (!waitingForUserInput) {
console.log(customer);
process.exit(0);
}
}
};

startAndPollAuthentication();

Poll outcomes​

Every call to /api/auth/poll ends in one of the outcomes below.

OutcomeHTTP statuserrorCodeBody
Still waiting for the user200-waitingForUserInput: true, statusMessage: "Beðið eftir að notandi auðkenni sig", no customer
Authenticated200-customer filled in, statusMessage: "Ok"
Request expired403authentication.error.audkenni.forbiddenresponseStatus.message: Rann út á tíma
Cancelled by the user403authentication.error.audkenni.forbiddenresponseStatus.message: Notandi hætti við auðkenningu.
Other failure reported by the ID provider403authentication.error.audkenni.forbiddenresponseStatus.message with the reason, for example Villa í innri kerfum (provider internal error) or Villa í samskiptum (communication error)
Error on our side while checking the request500authentication.error.audkenni.pollresponseStatus.message with the details

Error responses have this shape:

{
"responseStatus": {
"errorCode": "authentication.error.audkenni.forbidden",
"message": "Notandi hætti við auðkenningu.",
"errors": []
}
}

A 200 with waitingForUserInput: false and no customer (statusMessage: "Processing") means we are still preparing the result. Keep polling.

Telling a timeout from a cancel​

A timeout and a cancel both return 403 with the same errorCode, authentication.error.audkenni.forbidden. Only responseStatus.message differs:

responseStatus.messageMeaning
Rann út á tímaThe request expired before the user answered
Notandi hætti við auðkenningu.The user cancelled the authentication

These two texts are the contract for telling the cases apart. Match them exactly, including the final period in Notandi hætti við auðkenningu.. Other messages describe other failures, for example Notandi fannst ekki (user not found) or the generic Því miður tókst ekki að framkvæma umbeðna aðgerð. Vinsamlega reynið aftur. New messages can appear, so fall back to a generic "please try again" message for any text you do not recognise.

Any 403 from /api/auth/poll is final. Do not keep polling the same authRequestId after one, and start a new authentication with /api/auth/start instead.

Failure to start​

/api/auth/start can also fail with a 403 and errorCode authentication.error.audkenni.start. For example, responseStatus.message is Notandi fannst ekki when the person has no electronic ID for that phone number or social security number. No authRequestId is returned in this case, so there is nothing to poll.

Expiry and polling window​

How long an unanswered request stays open is decided by the electronic ID provider, not by us. These durations are approximate:

MethodAn unanswered request expires after
Simabout 90 seconds, sooner if the phone cannot be reached
Appabout 2 minutes

On our side a request is kept for at most 5 minutes after /api/auth/start. An authentication that is approved later than that cannot be completed.

We recommend:

  • Poll every pollingInterval seconds, as returned by /api/auth/start.
  • Stop on the first final answer: a 200 with customer filled in, or any 4xx/5xx.
  • Use a safety ceiling of about 3 minutes in total. A shorter cut-off, such as 60 seconds, ends some successful Sim authentications before the user has answered.

Device link login lets a person authenticate by scanning a QR code with their electronic ID app, or by opening a link on the same device. You do not need the person's phone number or social security number, because their identity is learned after they authenticate.

It uses two POST requests, like the methods above:

  • Call /api/auth/devicelink/start to start a session and get the link to show.
  • Call /api/auth/devicelink/poll every pollIntervalSeconds until the person has authenticated or the session ends.

Both calls require your API credentials in the Authorization header, as described in Authentication. The flow key must belong to an active Auth flow of your company. A session can only be polled with the credentials of the company that started it, and with the flow key it was started with. A session is only available for polling for 30 minutes after it was started.

Starting a session​

## Request

POST /api/auth/devicelink/start HTTP/1.1
Host: onboardingdev.taktikal.is
Accept: application/json
Content-Type: application/json
Authorization: Basic base64(companyKey:ApiKey)
{
"FlowKey": "abc123abc123"
}

## Response
{
"sessionId": "9d1c5b7e-4c6f-4f0e-9a43-0f2d8f4b7c11",
"deviceLinkUrl": "https://example.invalid/device-link?token=abc",
"pollIntervalSeconds": 2
}

Request parameters​

  • FlowKey (required) is the key of an Auth flow, see Parameters above.
  • Web2App (default false) set to true for a same-device login, where the person opens deviceLinkUrl as a link on the device that has the app. Leave it out for the default cross-device login, where the person scans a QR code.
  • InitialCallbackUrl is where the person is sent back to after a same-device login. It is required when Web2App is true, and must be an absolute https URL without a fragment (#...). It is ignored for QR login.
  • DisplayText is the text shown to the person in the app. If you leave it out, the display text of the flow is used.
  • Ssn is optional. When set, only the person with that Icelandic social security number can complete the login. When left out, anyone who scans the QR code can.

Response parameters​

  • sessionId identifies this login session. Send it with every call to /api/auth/devicelink/poll.
  • deviceLinkUrl is the link to show to the person.
  • pollIntervalSeconds is the interval between calls to /api/auth/devicelink/poll in seconds.

Showing the QR code​

For the default cross-device login, render deviceLinkUrl as a QR code and show it to the person. The link changes over time, so the QR code on screen goes stale if you leave it as it is. Every poll that is still waiting returns a fresh deviceLinkUrl. Redraw the QR code from it each time.

For a same-device login (Web2App), use deviceLinkUrl as a normal link or button instead of a QR code. After the person has authenticated in the app they are sent to your InitialCallbackUrl. The callback is a browser GET to your InitialCallbackUrl, and it carries two extra query parameters, sessionSecretDigest and userChallengeVerifier:

https://your-app.example.com/login/return?value=your-own-id&sessionSecretDigest=abc123&userChallengeVerifier=xyz789

Any query parameters that were already part of your InitialCallbackUrl, such as value above, are kept. Use one to tell which login the callback belongs to. Read the two values from the query string and send them unchanged as SessionSecretDigest and UserChallengeVerifier in the poll request. The poll for a same-device login fails without them. Do not send them for QR login.

Polling a session​

## Request

POST /api/auth/devicelink/poll HTTP/1.1
Host: onboardingdev.taktikal.is
Accept: application/json
Content-Type: application/json
Authorization: Basic base64(companyKey:ApiKey)
{
"SessionId": "9d1c5b7e-4c6f-4f0e-9a43-0f2d8f4b7c11",
"FlowKey": "abc123abc123",
"LookupType": "Name"
}

## Response while waiting
{
"waitingForUserInput": true,
"deviceLinkUrl": "https://example.invalid/device-link?token=def"
}

## Response when authenticated
{
"waitingForUserInput": false,
"statusMessage": "Ok",
"customer": {
"name": "Test User",
"ssn": "1234567890",
"token": "f19b032a237e4fbc94f3",
"flowKey": "abc123abc123"
}
}

Request parameters​

  • SessionId (required) is the sessionId you received from /api/auth/devicelink/start.
  • FlowKey (required) must be the same flow key that was used to start the session.
  • LookupType works as for /api/auth/poll, see above. The default is Name.
  • SessionSecretDigest and UserChallengeVerifier are only for same-device (Web2App) login, see above.

Response​

  • While the person has not authenticated yet, waitingForUserInput is true, there is no customer and no statusMessage. For QR login deviceLinkUrl holds the link to redraw the QR code from; for a same-device login it is empty.
  • Once the person has authenticated, customer is filled in according to LookupType and statusMessage is Ok.
  • A 200 with waitingForUserInput: false and no customer (statusMessage: "Processing") means we are still preparing the result. Keep polling.

The statusMessage and responseStatus.message texts come from the ID provider and are often in Icelandic. Do not parse them, except for the two texts described under Telling a timeout from a cancel.

Polling again after a successful poll is safe. A repeat poll with the same SessionId, FlowKey and LookupType returns the same customer as the first successful poll, with no extra lookup cost and no duplicate customer. A repeat poll with a different LookupType runs its own lookup and returns a different customer.

Errors​

SituationHTTP statuserrorCode
Missing or invalid API credentials (start and poll)401-
Start: FlowKey is not an Auth flow400authentication.error.flow.not.auth
Start: no active flow with that FlowKey for your company (including a flow of another company)403authentication.error.forbidden
Start: session could not be started403authentication.error.audkenni.start
Poll: session unknown, expired, or started by another company403authentication.error.session.expired
Poll: FlowKey is not the one the session was started with403authentication.error.session.flow.mismatch
Poll: request expired, cancelled by the user, or another failure reported by the ID provider403authentication.error.audkenni.forbidden
Poll: no customer could be created from the authentication403authentication.error.forbidden
Poll: error on our side while checking the session500authentication.error.audkenni.poll

The error body has the same shape as for /api/auth/poll, see poll outcomes, including how to tell a timeout from a cancel. A session that belongs to another company is reported as authentication.error.session.expired, the same as one that does not exist. Any 403 from /api/auth/devicelink/poll is final. Start a new session with /api/auth/devicelink/start instead of polling the same sessionId again.

Old method​

Example request to authenticate a person​

## Request

POST /api/auth HTTP/1.1
Host: onboardingdev.taktikal.is
Accept: application/json
Content-Type: application/json
Authorization: Basic <Base64-encoded companyKey:apiKey>
{
"PhoneNumber": "1234567",
"FlowKey": "abc123abc123",
"LookupType": "NameAddress"
}

## Response
{
"name": "Test User",
"ssn": "1234567890",
"phoneNumber": "1234567",
"address": "Address 5",
"postalCode": "555",
"city": "Gotham City",
"token": "f19b032a237e4fbc94f3",
"flowKey": "abc123abc123",
"meta": {
"GenderCode": "1",
"Citizenship": "IS"
}
}