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

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",
  "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

Response parameters

• verifcationCode which the user will see in their device and we strongly recommend to display on your end.
• authRequestId is a unique key for this login session, you will need to send with every call to /api/auth/poll (see below) until user logs in or request times out (180 seconds).
• 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.
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

Node.js

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

C#

var httpClient = new System.Net.Http.HttpClient();
var resp = await httpClient.PostAsJsonAsync("https://onboardingdev.taktikal.is/api/auth/start", new
{
    FlowKey = "abc123abc123",
    PhoneNumber = "1234567",
    AuthenticationContextType = AuthenticationContextType.Sim // or just "Sim" if you don't want to use an enum
});

var startAuthResponse = await resp.Content.ReadFromJsonAsync<StartAuthResponse>();
while (true)
{
    await Task.Delay(2000);
    var pollResponse = await httpClient.PostAsJsonAsync("https://onboardingdev.taktikal.is/api/auth/poll", new
    {
        FlowKey = "abc123abc123",
        AuthRequestId = startAuthResponse.AuthRequestId,
        LookupType = LookupType.NameAddressFamily // or just "NameAddressFamily" if you don't want to use an enum
    });

    if (pollResponse.IsErrorResponse())
    {
        // log error
        break;
    }

    var parsedResponse = await pollResponse.Content.ReadFromJsonAsync<PollCustomer>();
    if (!parsedResponse.WaitingForUserInput)
    {
        // access customer object here parsedResponse.Customer
        break;
    }
}

public class StartAuthResponse
{
    public string AuthRequestId { get; set; }
    public string VerificationCode { get; set; }
}

public class PollCustomer
{
    public Customer Customer { get; set; }
    public string StatusMessage { get; set; }
    public bool WaitingForUserInput { get; set; } = false;
}

public class Customer
{
    public string Name { get; set; }
    public string Ssn { get; set; }
    public string PhoneNumber { get; set; }
    public string Email { get; set; }
    public string Address { get; set; }
    public string PostalCode { get; set; }
    public string City { get; set; }
    public string Token { get; set; }
    public string FlowKey { get; set; }
    public Dictionary<string,string> Meta { get; set; }
}

PHP

<?php

$request = new HttpRequest();
$request->setUrl('https://onboardingdev.taktikal.is/api/auth/start');
$request->setMethod(HTTP_METH_POST);

$request->setHeaders(array(
  'Host' => 'onboardingdev.taktikal.is',
  'Content-Type' => 'application/json',
  'Accept' => 'application/json'
));

$request->setBody('{
  "PhoneNumber": "1234567",
  "FlowKey": "abc123abc123",
  "AuthenticationContextType": "Sim"
}');

try {
  $response = $request->send();
  $startAuthResponse = $response->getBody();
  while(true) {
    sleep(2)
    $request->setBody('{
        "AuthRequestId": startAuthResponse.authRequestId,
        "FlowKey": "abc123abc123",
        "LookupType": "NameAddressFamily"
    }');
    $response = $request->send();
    $pollResponse = $response->getBody();
    if(!$pollResponse.waitingForUserInput) {
        echo $pollResponse
        break;
    }
  }
} catch (HttpException $ex) {
  echo $ex;
}

Errors

The endpoint /api/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"
    }
}