Authentication

Obtaining and Using API Keys

Obtaining an API Key

To obtain a new API key, please contact hello@imin.co and we will issue you a key as soon as possible.

Note

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.

Danger

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

Caution

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.

Danger

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.

Danger

Unless we have expressly agreed a client-side integration with you, all requests must be made server-side. If you are found to be using, or attempting to use, API key(s) from within browsers without our permission, we reserve the right to suspend your access to our Platform without notice.

Keeping your Key Safe

By default, an API key should be treated as a credential equivalent to a password: it must be kept out of any version control system and, wherever possible, used only in server-side requests. For accounts with Booking Platform access, the key can place orders and read customer personal data, so exposing it presents a genuine security risk.

Where a key is used solely to retrieve open data for display — for example, to power an embedded timetable or map via our Discovery API — it may be used from the front end, provided a client-side integration has been agreed with us. As the data is published under an open licence, no personal data is exposed; the only consequence of an unauthorised party using the key is that they may consume your API quota, which is a commercial concern rather than a security one.

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.