Authentication

To successfully connect to the platform the user needs an authentication token and a session token. The authentication token is used to acquire a new session token (initially and when the current one expires) and the session token is used for all operations.

Basic authorization header is used for acquiring a session token, where credentials is the base64 encoding of the authentication token.

Authorization: Basic <credentials>

All subsequent requests to the API require the Authorization Bearer header including the session token:

Authorization: Bearer wxKj3JV6ET1dXVou77675tMqC...

The authentication object

Attribute

Type

Description

id

uuid

The unique identifier for the authentication.

device_id

uuid

The unique identifier for the device attached to the authentication token.

status

string

The status of the authentication. created approved rejected

token

string

The authentication token.

error_code

string

The error key, in case of an error.

error_message

string

The error message, in case of an error.

expires_at

time

The time when the authentication token expires, if set.

Example

{
"id": "8d3f94b0-87d0-497f-810c-9b150d42ed05",
"device_id": "d23ddbff-4801-48b6-9651-0afccbd5b732",
"status": "approved",
"token": "wxKj3JV6ET1dXVou77675tMqC...",
"error_code": "",
"error_message": "",
"expires_at": "2017-10-19T17:02:03.181879Z"
}

The session object

Attribute

Type

Description

id

uuid

The unique identifier for the session.

token

string

The authentication token.

expires_at

time

The time when the session expires, if set.

created_at

time

The time when the session was created.

Example

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

Get authentication token

Post identity type + value (e.g. phone number), type of authentication (e.g. "sms") and device. The response will include an ID and status for lookup.

Request
Response
Request

POST /v1/tokens

Attribute

Type

Description

identity.type

string

The name of the identity.required email

phone username

identity.value

string

The value which to look up the user by, e.g. a username. required

authenticator

string

The name of the authenticator. Can be password, sms or a custom authenticator. required

secret

string

The secret required for the authenticator. required

device

Device

The user device information. required

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

423 Locked

Authentication process was not approved. User account has been temporarily locked.

403 Forbidden

Authentication process was not approved. User account has been permanently locked.

Get authentication token – Step 2

Post the secret (e.g. verification code) and PIN (depends on the authenticator type).

Request
Response
Request

POST /v1/tokens/{id}/secret

Attribute

Type

Description

secret

string

The secret required to authenticate. required

pin

string

The PIN for the user wanting to authenticate. required

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

400 Bad Request

Authorization rejected.

423 Locked

User account is temporarily locked.

403 Forbidden

User account is locked.

Get authentication token status

Request
Response
Request

GET /v1/tokens/{id}

Response

201 Created

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

Delete authentication token

Request
Response
Request

DELETE /v1/tokens/{id}

Response

200 OK

Authorization token was deleted.

401 Unauthorized

An active authorization token was not found.

Get session token

Send an authentication token as an Authorization header and receive a session token as well as the date and time when the session expires.

Request
Response
Request

POST /v1/sessions

Response

201 Created

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

401 Unauthorized

The authentication token was not found or is invalid.

403 Forbidden

User account is locked.

Verify session token

Verify that a specific session token is valid by sending the token as an Authorization header. Returns 200 OK if the session token is valid.

Request
Response
Request

POST /v1/sessions/verify

Response

200 OK

The session token is valid and active.

401 Unauthorized

The session token was not found or has expired.