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.
Step 2: Generate a random nonce value
This can be any random string but should be unique every time.
Step 3: Calculate the secret
The secret is calculated according to the following structure:
Step 4a: Authenticate with credentials
Valid username and password of a user within your account.
Step 4b:Authenticate with access token
Obtained from a successful credential authentication. This should be used to refresh an expired token.
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.
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.
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'.
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 deltetion of your live data is perminent 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.
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.
Compressed Gzip responses
When responses are given from the API, the content encoding of the response will need to be checked. If the value matches Gzip the response stream will need to be decompressed before it is deserialized.
If the response does not contain Gzip in the "content-encoding" parameter, the response can be deserialized directly into your object.
For more information regarding Gzip, we would recommend heading over to StackOverflow and follow guides on decompressing Gzip
HTTP status codes
The HTTP status codes and their meaning are as follows:
||A successful API call/action has been received.
||The API request has an error in it.
||Can’t authenticate with those credentials. Check credentials and get a new access token if error persists.
||Permission not granted to execute API call/action.
||Internal Server Error
||Something unexpected happened, contact WhosOff support.
||Unable to communicate with API server, contact WhosOff support.
||Unable to complete call/action within permitted time, contact WhosOff support
The following samples show typical responses you may see.