Authentication

There are three types of authentication supported for API access, which must be successful for any API request.

API Key

This is the most conventional type of authentication.  There are two types of API keys: site and company.  A site key can be obtained and reset from the Configuration page in the administration interface.  A company key can be obtained and reset from the company page.  As the type names imply, a site key can be used for API calls for any company, plus for company and site user management; a company key can only be used for API calls for one company.  Company keys are prefixed with companyid- to identify the company.  Both types of keys contain a large number of random characters.

Note that if OpenID Connect is used for authentication, API Key authentication is required for API requests.

To use the key, specify an Authorization header in each request:

Authorization: X api-key

The value X can be any word (the conventional word is "Bearer"), and the second word is the full API key value.

You should generally store this value in an environment variable or secure file for use by your API integration code, so that is easy to update if the value is reset.

Session ID

This method requires that an initial authorization request is performed, and a session ID value is returned.  That session ID is a random string value and is valid for a configurable amount of time (12 hour default), and can be supplied in a request header until it expires, at which time a new authorization request is required.

To obtain a session ID use this request URI:

Request

Endpoint: /api/auth

Parameters:

•userid=siteuser
or
locid=locid@compid

•password=password

Response

The response is three text lines separated by newlines:

•Session ID

•true or false if the session is associated with an administrative login

•Company IDs, comma-separated, that are valid for this session (this is null for administrative or location logins)

To use the session ID in each request, use one of these methods:

•Add a field sid=sessionID to the fields of any request

•Add a header X-CPSID: sessionID to the request

Warning: this request, if submitted as a GET request and if http logging is turned on, will cause user and password credentials to appear in server log files.  A POST request is recommended.

Dynamic Auth String

A dynamic auth string is a calculated value that is supplied with each request in a header.  The calculation includes a timestamp that must be within a tolerance of plus or minus 10 minutes of the server time, so it is important that the API client machine and server have well synchronized clocks.  The timestamp is in UTC time, so it not affected by time zones.

This style of authentication can be used when the login and password can be securely stored by the client application, to avoid session expiration.

The authorization string is composed of 4 segments, separated by forward slashes:

•The user ID.

•The time stamp, using Unix time, which is the seconds since Jan 1, 1970 00:00:00 UTC.  This time value is available in most programming languages.

•A random number.

•An MD5 hash of the concatenated timestamp, random number, and the user's password, as a case-insensitive hexadecimal value.

To illustrate, here is a Javascript function called with a login and password (md5() returns hex encoding of the hash):

function authStr(l,p){

    var r=String(Math.floor(Math.random()*(2**32)));

    var t=String(Math.round(Date.now()/1000));  // convert milliseconds to seconds

    var s=l+"/"+t+"/"+r+"/"+md5(t+r+p);  // md5 is a function returning the hexadecimal string encoded hash

    return s;

}

This auth string is calculated for each request and a header added:

X-CPAUTH: auth-string