How does an API key work?

i-Reserve has two kinds of API key, each with a different purpose. Both are managed via Configuration → System → API. Both are explained below.

1. Anonymous key (per license)

Different security levels apply to the web service. Anonymous access is possible for anonymous calls, such as requesting the characteristics of an object.

The anonymous calls can be secured. This obviously makes the calls less accessible. This scenario is particularly applicable for system applications.

On the configuration page it is possible to create or replace a key. One key is possible per license. Once the key has been set, it must be supplied with every anonymous request (in the IRES-SECRET header). This key selects the license and does not log any user in.

2. API key per user

Available from i-Reserve version 5.42. In addition to the anonymous key, an API key can be created per user. Unlike the anonymous key, this one authenticates the call: the call is made as if that user were logged in, with their rights (authorisation profile). This lets an integration access the API without a separate login call each time and without transmitting a password.

Creating. Go to Configuration → System → API. At the bottom, under the per-user keys, select the desired user and click Create user API key. The full key is then shown only once — store it somewhere safe straight away. The key is stored hashed (since version 5.45) and cannot be viewed afterwards; the overview only shows a masked version.

Format. A user key has the form sk_<license>_<user>_<secret>.

Using. Supply the key with each call in a header, for example X-API-KEY: sk_… or Authorization: Bearer sk_….

Revoking. In the list of keys, remove a key with the trash icon. The key is invalid immediately afterwards.

See also What security modes are used? for all authentication methods.