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
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"
  }
}
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
POST /verifications
{
  "type": "sms",
  "key": "phone",
  "value": "+44 123 1234 1234"
}
201 Created
{
  "id": "f346ced3-f80c-45d9-a9f5-a2b0288cb126",
  "type": "sms",
  "status": "pending",
  "expires_at": "2017-04-19T14:35:09.308904Z"
}
Request – Step 2
Response
POST /verifications/f346ced3-f80c-45d9-a9f5-a2b0288cb126/data
{
  "data": "123456"
}
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
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"
  }
}
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
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"
  }
 }
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
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"
  }
 }
201 Created
{
  "id": "8d3f94b0-87d0-497f-810c-9b150d42ed05",
  "status": "pending",
  "token": "wxKj3JV6ET1dXVou77675tMqC..."
}
Request – Step 2
Response
POST /v1/tokens/8d3f94b0-87d0-497f-810c-9b150d42ed05/secret
{
  "secret": "111111",
  "pin": "1234"
}
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
POST /sessions
Authorization: Basic YWxhZGRpbjpvcGVuc2VzYW1l
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.
REST Product API
Project Preferences
Last modified 2yr ago