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
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
POST request parameter
If your API request is a POST request, the API key can be provided as 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.