Authentication Flow

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.

If a user is required to provide a NIN, phone number or email, the user must provide verification data. See "Create with verification".

Request
Response
Request

POST /users

{
"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"
}
}
Response

201 Created

{
"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.

Request – Step 1
Response
Request – Step 1

POST /verifications

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

201 Created

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

POST /verifications/f346ced3-f80c-45d9-a9f5-a2b0288cb126/data

{
"data": "123456"
}
Response

200 OK

{
"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.

Request
Response
Request

POST /users

{
"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"
}
}
Response

201 Created

{
"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.

Request
Response
Request

POST /tokens

{
"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"
}
}
Response

201 Created

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

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

Request – Step 1
Response
Request – Step 1

POST /tokens

{
"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"
}
}
Response

201 Created

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

POST /v1/tokens/8d3f94b0-87d0-497f-810c-9b150d42ed05/secret

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

201 Created

{
"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).

Request
Response
Request

POST /sessions

Authorization: Basic YWxhZGRpbjpvcGVuc2VzYW1l
Response

201 Created

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

400 Bad Request

The authentication token was found, but the user account is locked or invalid.

401 Unauthorized

The authentication token was not found or is invalid.

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.