WhosOff API

Authorisation & security

In order to request access to your data, authentication needs to be successfully completed to obtain a bearer token. This can be done in two ways; by supplying user credentials (username and password) or through a valid access token. Alongside the credentials or access token, an IP address, a number once (nOnce), a secret, and a unique App Id must also be supplied. See API Authenticate Object for more information on the request and response objects.

Create an access token
Step 1: Obtain app credentials

In this section, we create an access token.

For example, our app credentials might be

app_id = "MN500Q8lk5jp0rEm" secret = "QtOSeNmh3DY6AuMO" (client secret)

Step 2: Generate a random nonce value

This can be any random string but should be unique every time.

Example, random nonce

nonce="2029-03-14T13:24:10.832Z"

Step 3: Calculate the secret

The secret is calculated according to the following structure:

Example, calculate using Secure Hash Algorithm

// secret = SHA512(nonce + secret) secret = SHA512(2029-03-14T13:24:10.832ZQtOSeNmh3DY6AuMO"

Step 4a: Authenticate with credentials

Valid username and password of a user within your account.

Authenticate with credentials

curl --location --request GET '{root}/authenticate/with-credentials' \ --header 'Content-Type: application/json' \ --data '{ "username": "{username}", "password": "{password}", "ip_address": "{ip_address}", "nonce": "{nonce}", "secret": "{secret}", "app_id": "{app_id}" }'

Step 4b:Authenticate with access token

Obtained from a successful credential authentication. This should be used to refresh an expired token.

Authenticate with access token

curl --location --request GET '{root}/authenticate/with-access-token' \ --header 'Content-Type: application/json' \ --data '{ "access_token": "{access_token}", "ip_address": "{ip_address}", "nonce": "{nonce}", "secret": "{secret}", "app_id": "{app_id}" }'

IP address

IP address needs to be supplied to check if the request has permission from that location. Multiple IP address ranges can be added by the super user within WhosOff.

nOnce (number once) - generated by developer on each new authentication request

nOnce is a randomly generated, unique, 32 character string which is used in conjunction with the client secret to create a unique single use SHA512 hash.
Note: this could be the current DateTime to millisecnds '2029-03-14T13:24:10.832Z' and/or a Guid - so long as it is never reused.

Secret

The secret is a unique single use string which is created using the nOnce + supplied client secret (obtained in company settings) then hashed using the SHA512 algorithm.

App Id - obtained in company settings

The App Id is supplied to identify your unique API application. This is used in the initial request for an access token and in all proceeding calls in the call header.

---

Bearer token

Once authentication has been successful, an access token will be returned. This should now be used as in the example below along side your app-id and the content type 'application/json'.

Example call to get user by id

curl --location --request GET '{root}/user/get-by-id/{user_id}' \ --header 'Authorization: Bearer {access_token}' --header 'app-id: {app-id}' --header 'Content-Type: application/json' \ --data '{}'

Testing your connector

It is strongly recommended that all testing uses the sandbox root while you build your custom integration - this can be found in company settings. To test your first authentication, you may wish to use Postman to ensure the connection is working. Please also be aware that any writing, editing and deletion of your live data is permanent and directly impacts your own data. Any changes to your data are your responsibility, so please ensure you have tested extensively in sandbox before pointing to the live root.

Unauthorised calls

Any unauthorised called will get a standard 400 response explaining why the authorisation failed. Below is an example of an invalid token. This could require reauthentication with credentials or a renewal of an expired token.

Example 400 response for Invalid Token

{ "Data":[], "Errors": [ { "Code": "TOK004", "Message":"Invalid Token" } ] }