Authentication

Before the API can be used, an API key must be generated to authenticate each request. An API key is a random string of characters, and is equivalent to the user and password. The access granted is identical to the access for the user.

To generate a key, log into Haplo as an administrator. Click your user name in the top right, then System Management in the pop up menu. Click Users then the name of the user you wish to use for authentication. Scroll down, and click New API key. Create the key, then click Reveal this API key to show the key.

The remote system will act as if it is logged in as this user. You can use an existing user which has the permissions you want to grant, but management is easier if you create a special user for each system which will use the API.

NOTE: It is recommended you fill in a path prefix for this API key which restricts the APIs it can access.

Authenticating with an API key

HTTP Basic authentication

The recommended option for authenticating with a key is to use HTTP Basic authentication. Note that Haplo does not request authentication with the WWW-Authenticate header.

The username must be haplo, and the password is the API key. For example, a curl command might be:

    curl --user haplo:0123456789ABCDEF0123456789ABCDEF0123456789AB \
        https://application.example.com/api/example

where the generated API key was 0123456789ABCDEF0123456789ABCDEF0123456789AB.

POST request parameter

If your API request is a POST request, the API key can be provided as the _ak parameter.

The _ak request parameter cannot be used with a file upload multipart/form-data request because the authentication takes place before the request body is parsed.

Legacy authentication header

To support applications which use an older authentication method, you can authenticate by passing the API key in a X-ONEIS-Key HTTP request header.