API Keys
API Keys let each user of a generated application create personal keys for external tools and integrations, without sharing their password.
Enabling
Enable the API Keys option in the application identification (Settings > Applications) and generate it again. Applications that do not enable the option do not get the page, the menu entry or the endpoints.
Managing keys
When the option is enabled, logged-in users find an API keys entry in the user avatar menu. Guest and public users do not have access to it. The page lets each user manage their own keys:
- Create - use Insert below the table. A key needs a name and an expiration date. The name is unique per user and has at most 100 characters. The expiration date is mandatory and cannot be later than the maximum validity (see Maximum validity).
- Copy - the full key is shown only once, right after it is created or rotated. Copy it at that moment.
- Rotate - replaces the value of a key by a new one. The key keeps its name, and the old value stops working immediately. No history of the old value is kept, so any tool that uses it has to be updated with the new key. The key keeps its original validity period, counted from today and never longer than the maximum validity. The new value is shown once, as when a key is created. A revoked key cannot be rotated: activate it again first.
- Revoke and reactivate - a revoked key stops being valid, and can be activated again while it has not expired.
- Delete - permanently removes the key, after a confirmation.
The list shows these columns:
- Name
- API key - the visible prefix of the key.
- Status - Active, Expiring (30 days or less until it expires), Revoked or Expired, each with its own colour.
- Created
- Expiration
- Last used
Users only see and manage their own keys, and changes are not allowed while the system is in maintenance mode.
Maximum validity
The longest validity allowed for a key is set in WebAdmin, in the API keys maximum validity property, in days. The default is 365 days. The page tells users the limit, and the server enforces it when a key is created or rotated.
How keys are stored
Each key starts with qg_ followed by 256 bits of randomness. Only a SHA-256 hash of the key and its first 12 characters (the visible prefix) are stored, so a lost key cannot be recovered and has to be replaced by a new one. Deleting a user also deletes their keys.