Authentication
Every request needs an integration key, sent as a bearer token:
Authorization: Bearer nik_<prefix>_<secret>Requests and responses are JSON over HTTPS. Every path is relative to the base URL of the environment you call. See Overview for the base URLs.
Getting a key
Ask your Konsol contact for an integration key. You get one key for each system you connect. Keep it secret: anyone with the key can act as your system.
What a key can reach
Your Konsol contact sets what each key can reach:
- your whole organisation,
- one business unit,
- one vendor, or
- one acquirer.
This is the key's reach. A record outside it returns 404, as if it did not exist, and lists leave it out.
When a key is refused
| Status | Cause |
|---|---|
401 | The key is missing, malformed, unknown, revoked or expired. Every cause returns the same body. |
403 | The key's role does not allow this action, or the action needs a key for your whole organisation. |
A revoked or expired key is refused from its next request.
Actions that need a key for your whole organisation
These actions need a key whose reach is your whole organisation. A key limited to a business unit, vendor or acquirer gets 403.
- Set a device up for a product, or release it from one.
- Issue an activation code.
- Read, write or clear a device's parameters.
- Enroll a trading in a product.
- Create an enterprise, or a company with no enterprise.
- Create an acquirer.
A key limited to one acquirer cannot change that acquirer's external_ref. To register or decommission devices, you need a key for your whole organisation or for one vendor. A vendor key works only with that vendor's devices.