Introduction

• Authentication is based on a combination of an authentication token and a session token.

• Authentication token can only be used to request a new session token while the session token is used for each operation in the API.

• Both tokens can have an expiration time, ideally the session token should be short lived (e.g. 15 minutes) while the authentication token can have a longer lifespan (e.g. a year).

• When the session token expires the client can request a new session token using the authentication token.

• When the authentication token expires the user has to perform a new login process.

Step 1 – Get an authentication token

There are two ways for the client to receive an authentication token:

• When a new user is created

• When a user logs in

Signup

Signup without verification

The client posts user data to the /users endpoint and receives a User object with an embedded authentication token.

{
  "first_name": "John",
  "last_name": "Dough",
  "username": "johndough",
  "pin": "1234",
  "device": {
    "id": "582a5abb-1335-4794-4855-11e067b8c55e",
    "make": "iPhone",
    "model": "iPhone6,2",
    "os_name": "iOS",
    "os_version": "8.0"
  }
}

{
  "id": "add5c52a-0c57-4d5c-7525-db14566f2f1a",
  "status": "active",
  "first_name": "John",
  "last_name": "Dough",
  "full_name": "John Dough",
  "username": "jondough",
  "country": "UK",
  "timezone": "Europe/London",
  "timezone_utc_offset": 0,
  "locale": "en-UK",
  "verified": true,
  "official": true,
  "token": {
    "id": "8d3f94b0-87d0-497f-810c-9b150d42ed05",
    "status": "approved",
    "token": "wxKj3JV6ET1dXVou77675tMqC...",
    "expires_at": "2017-09-04T12:25:48.827724Z"
  },
  "created_at": "2017-09-04T12:25:48.827724Z",
  "updated_at": "2017-09-04T12:25:48.827724Z"
}

Signup with verification

The client posts verification data to the /verifications endpoint. For some verification methods, this is a single step since the data will be provided immediately (e.g. passport, driver's license, etc.). In other cases, this is a two-step process since the user must wait for verification data to arrive (e.g. SMS, email).

First, the client finished the verification process.

{
  "type": "sms",
  "key": "phone",
  "value": "+44 123 1234 1234"
}

{
  "id": "f346ced3-f80c-45d9-a9f5-a2b0288cb126",
  "type": "sms",
  "status": "pending",
  "expires_at": "2017-04-19T14:35:09.308904Z"
}

{
  "data": "123456"
}

{
  "id": "f346ced3-f80c-45d9-a9f5-a2b0288cb126",
  "type": "sms",
  "status": "approved",
  "expires_at": "2017-04-19T14:35:09.308904Z"
}

Then, once the verification process is done, the client can create the user. The ID of the verification object is included in a verifications array along with the user field being verified.

For example, if the field value is phone, and the verification's value (from the process above) matches the user's phone number, the user's phone number becomes verified. Verification objects of all types can be attached to the user, but only phone and email types will affect the user object directly.

{
  "first_name": "John",
  "last_name": "Dough",
  "username": "johndough",
  "phone": "+44 123 1234 1234",
  "pin": "1234",
  "verifications": [
    {
      "field": "phone",
      "id": "c5c18397-2ed7-43c1-b481-a5f3d3a96ef1"
    }
  ],
  "device": {
    "id": "582a5abb-1335-4794-4855-11e067b8c55e",
    "make": "iPhone",
    "model": "iPhone6,2",
    "os_name": "iOS",
    "os_version": "8.0"
  }
}

{
  "id": "add5c52a-0c57-4d5c-7525-db14566f2f1a",
  "status": "active",
  "first_name": "John",
  "last_name": "Dough",
  "full_name": "John Dough",
  "username": "jondough",
  "phone": "+44 123 1234 1234",
  "country": "UK",
  "timezone": "Europe/London",
  "timezone_utc_offset": 0,
  "locale": "en-UK",
  "verified": true,
  "official": true,
  "token": {
    "id": "8d3f94b0-87d0-497f-810c-9b150d42ed05",
    "status": "approved",
    "token": "wxKj3JV6ET1dXVou77675tMqC...",
    "expires_at": "2017-09-04T12:25:48.827724Z"
  },
  "created_at": "2017-09-04T12:25:48.827724Z",
  "updated_at": "2017-09-04T12:25:48.827724Z"
}

Login

Single step login (e.g. username + password)

The client posts login data to the /tokens endpoint and receives an authentication token. The login can be either a single step process (e.g. username + password) or a two-step process, where the user needs to provide a secret such as in the case of a phone number + SMS code flow.

{
  "identity": {
      "type": "username",
      "value": "jondough"
  },
  "authenticator": "password",
  "secret": "123456",
  "device": {
      "id": "582a5abb-1335-4794-4855-11e067b8c55e",
      "make": "iPhone",
      "model": "iPhone6,2",
      "os_name": "iOS",
      "os_version": "8.0"
  }
 }

{
  "id": "8d3f94b0-87d0-497f-810c-9b150d42ed05",
  "status": "approved",
  "token": "wxKj3JV6ET1dXVou77675tMqC..."
}

Two-step login (e.g. phone number + SMS code)

{
  "identity": {
      "type": "username",
      "value": "jondough"
  },
  "authenticator": "password",
  "secret": "123456",
  "device": {
      "id": "582a5abb-1335-4794-4855-11e067b8c55e",
      "make": "iPhone",
      "model": "iPhone6,2",
      "os_name": "iOS",
      "os_version": "8.0"
  }
 }

{
  "id": "8d3f94b0-87d0-497f-810c-9b150d42ed05",
  "status": "pending",
  "token": "wxKj3JV6ET1dXVou77675tMqC..."
}

{
  "secret": "111111",
  "pin": "1234"
}

{
  "id": "8d3f94b0-87d0-497f-810c-9b150d42ed05",
  "status": "approved",
  "token": "wxKj3JV6ET1dXVou77675tMqC...",
  "expires_at": "2017-10-19T17:02:03.181879Z"
}

Step 2 – Get a session token

The client posts to the /sessions endpoint, sending the authentication token with the Authorization: Basic header. If the authentication token is active, a session token object is returned. If the server replies with a 401 Unauthorized the authentication token is either invalid or has expired. If the server replies with a 400 Bad Request the user account is invalid (e.g. has been locked).

Authorization: Basic YWxhZGRpbjpvcGVuc2VzYW1l

{
  "token": "d2LRgT827mEcwXlSoEMztc8If...",
  "created_at": "2017-10-18T17:02:03.181879Z",
  "expires_at": "2017-10-19T17:02:03.181879Z"
}

Step 3 – Using the session token

From this point on, the client will send the session token with the Authorization: Bearer header for each request to the endpoints. If the server replies with a 401 Unauthorized the session token is either invalid or has expired.