Authentication

Obtaining and Using API Keys

Obtaining an API Key

To obtain a new API key, please contact [e-mail] and we will issue you a key as soon as possible.

Before you have an API key, you can explore the Events API by:

• Referring to our reference documentation to see example requests, responses, and descriptions of each endpoint; and

• Using our test API key to take a look at the dummy data ("Lorem Fitsum") in the Events API.

Please note, this functionality is only available for the Events API.

If you believe your key has been compromised, please contact your account manager who will issue you a new key as quickly as possible.

Using the API Key

Once you have a valid API key, making an authenticated request is again straight-forward. On each request, include HTTP request header X-API-KEY, set to the value of your valid API key. For example:

X-API-KEY: 6aa0fa074bec4a5cb0e8ed8fd36151ce

6aa0fa074bec4a5cb0e8ed8fd36151ce is included here for illustrative purposes only and is not a functional API key.

Single-Use API Keys

Each API key issued is to be used exclusively within only one of your digital service, unless you have our explicit permission to do otherwise. This means that if you are building more than one product, you will require more than one API key. For example, a web app and a mobile app will each require their own unique API key.

If you have a B2B2C product (i.e. you sell or licence to other businesses a product that uses the imin Platform, e.g. a whitelabel corporate wellbeing solution), you may require a custom licence setup for each re-use. Please get in touch to discuss your requirements in more detail.

If you are found to be using the same API key in a manner detailed above (or any other way that we deem to be misuse of a single-use API key) without our written permission, we reserve the right to suspend your access to our Platform without notice.

API Keys and Best Practice

Server-Side Connections

All requests must be made server-side, otherwise it will be possible to view your unique single-use API key(s) with a browser.

All request must be made server-side. If you are found to be using or are attempting to use API key(s) from within browsers without our express permission, we reserve the right to suspend your access to our Platform without notice.

Keeping your Key Safe

Your secret API key can be used to make any API call on behalf of your account. Ensure they are kept out of any version control system that you may be using. You should treat them as you would a password.

If you are using a header extension in your browser, we recommend turning off the header when you are not using the API to avoid revealing it when you visit other websites on that browser.

Prepare for Key Rotation

For security reasons, we will periodically rotate keys. Rotating keys means that we will add a new API key for your access. Then, after a period of time, we will deprecate the old API key so that only the new API key works. We will also do this early if our monitoring systems expect that keys are being used by unauthorised parties. We will always give notice before doing this.

If your app has been built by a technical team which is not in-house and full-time, e.g. a software agency, you may prefer to make sure that API keys can be changed without having to hire an agency. If API keys are stored in environment variables, make sure that the technical team have handed over how to update the environment variables to new values.