Skip to main content

Using the Auth API

Two POST requests are needed to authenticate a user:

  • First call /auth/start to start the authentication process
  • Then every two seconds call /auth/poll to check whether the user has authenticated

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

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
{
"PhoneNumber": "1234567",
"FlowKey": "abc123abc123",
"AuthenticationContextType": "Sim"
}

## Request for authentication via app

POST /api/auth/start HTTP/1.1
Host: onboardingdev.taktikal.is
Accept: application/json
Content-Type: application/json
{
"Ssn": "1234567890",
"FlowKey": "abc123abc123",
"AuthenticationContextType": "App"
}

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

The response will include the verifcationCode which the user will see in their device and we strongly recommend to display on your end. And authRequestId which you will need to send every two seconds to /auth/poll until user logs in or request times out (180 seconds).

The /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.
  2. NameAddress: Will return Name, SSN and legal address information. This has an additional lookup cost. This is the default value if no value is given for LookupType.
  3. NameAddressFamily: Returns Name, SSN, Address data, gender code, and family information. Note: Family lookup requires special permission.

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
{
"authRequestId": "1-147rag342352345",
"FlowKey": "abc123abc123",
"LookupType": "NameAddressFamily"
}

## 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": "Reykjavík",
"token": "f19b032a237e4fbc94f3",
"flowKey": "abc123abc123",
"meta": {
"ParnerSsn": "1231231245",
"FamilyNumber": "1234567890",
"GenderCode": "1",
"FamilyStatus": "3"
}
}
}

Examples code in different languages

const axios = require("axios");

const flowKey = "abc123abc123";

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

return data;
};

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

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();

Errors

The endpoint /auth/poll will return a 403 response if user is not authenticated and we are no longer waiting for him and the body will contain the reason why

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
{
"PhoneNumber": "1234567",
"FlowKey": "abc123abc123",
"LookupType": "NameAddressFamily"
}

## Response
{
"name": "Test User",
"ssn": "1234567890",
"phoneNumber": "1234567",
"address": "Address 5",
"postalCode": "555",
"city": "Reykjavík",
"token": "f19b032a237e4fbc94f3",
"flowKey": "abc123abc123",
"meta": {
"ParnerSsn": "1231231245",
"FamilyNumber": "1234567890",
"GenderCode": "1",
"FamilyStatus": "3"
}
}