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

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

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 /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"
    }
}