An API key lets one of your own systems, such as a warehouse or ERP integration, call the API as your account. The key acts like a user: it holds a role and can do exactly what that role allows, in this account only.
The app shows the full key only once. After you close the dialog, nobody can see it again, not even you. If you lose it, revoke it and create a new one.
Your system sends the key in the X-Api-Key header of each request, together with the usual realm Authorization header. The API documentation link on the API keys tab, and the link in the dialog, open the API reference with requests, responses and examples.
Revoke a key when the integration stops, or when you think someone else has it.
You cannot undo a revocation or extend a key. To keep an integration working past the expiry date, create a new key before the old one runs out, then switch the integration to it.
| Column | What it shows |
|---|---|
| Name | The name you gave the key. |
| Key | The first characters of the key, so you can tell keys apart. |
| Role | The role the key holds. |
| Status | Active, Expired or Revoked. |
| Expires | When the key stops working. |
| Last used | When the key was last used and from which IP address, or "Never used". |
| Created by | Who created the key, and when. |
Use All, Active, Expired and Revoked above the list to filter by status, and Search API keys to find a key by name. Revoke shows only on active keys.
| Message title | What it means | What to do |
|---|---|---|
| "Role not allowed" | The role is above yours in this account. | Choose a role at or below your own. |
| "API key limit reached" | The account already has the most active keys allowed. | Revoke a key you no longer use, then try again. |
| "Invalid expiry" | The expiry is longer than your installation allows. | Choose a shorter period. |
If the Role list says "No role can be assigned to an API key in this account.", no role is at or below yours. Ask a user with a higher role to create the key.
Some actions are never open to an API key, whatever its role, such as signing in or creating users, roles and other keys. The API then answers "Not available to API keys".