API Keys

API keys let scripts and other clients access the Nzyme REST API without an interactive login. A key always belongs to a single user and inherits the permissions of that user: Everything the user can see and do in the web interface, a client using one of their keys can see and do through the API. There are no separate permissions for API keys.

The complete REST API is documented in the interactive API browser at https://api.docs.nzyme.org/. Every endpoint is listed there together with its parameters, request bodies and response schemas.

Managing your API keys

Every user manages their own API keys on their user profile page. Click your name in the top left corner of the web interface to get there. The API Keys section lists all your existing keys and lets you create new ones.

Creating a key

To create a key, enter a name and select an expiration period. The name is only used to help you recognize where a key is used, for example Nzyme CLI or Inventory Export Script.

Keys expire after 30, 90, 180 or 365 days. You can also create keys that never expire, but we recommend a regular rotation of keys. An expired key is rejected like a wrong password and must be replaced by a new key.

Warning

The plaintext key is shown exactly once, directly after you created it. Nzyme only stores a hash of the key and cannot show it to you again. Copy the key to a safe place like a password manager or your secrets management system before you leave the page.

Reviewing and deleting keys

The Your API Keys table shows the name, creation date, expiry and last activity of each key. The last activity is updated every time a client successfully authenticates with the key, so you can easily spot keys that are no longer in use and should be deleted.

Deleting a key takes effect immediately. Any client that is still using the key will receive an authentication error on its next request. Deleting a key never affects other keys or your interactive sessions.

Required permission

Users need the Manage own API Keys permission to create and delete their own keys. Administrators grant this permission like any other feature permission on the user details page. Organization administrators and super administrators always have it.

Removing the permission from a user does not delete the keys they already created. Those keys continue to work until they expire or are deleted.

Reviewing keys of other users

Organization administrators and super administrators can review the API keys of all users within their scope of access. The users table shows the number of keys each user has, and the user details page lists all keys of a user with the same name, creation date, expiry and last activity information the user sees on their profile page.

Nzyme records a system event every time a user creates an API key. You can subscribe to these events to be notified about new keys, as described in the alerting documentation.

Using an API key

Pass the key as a bearer token in the Authorization header of every request. All API keys start with the prefix nzk_, which is how Nzyme tells them apart from interactive session tokens.

curl -H "Authorization: Bearer nzk_YOUR_KEY_HERE" \
  https://yournzyme.example.org:22900/api/user/profile

The request above returns the profile of the user who owns the key. The REST API is served on the same port as the web interface and is subject to the same TLS configuration. Refer to the interactive API documentation for all available endpoints.

Security considerations

Treat an API key like a password. Anyone who has the key can act as the user who created it, within the limits of that user's permissions.

API keys are not subject to multi factor authentication. Creating a key requires an interactive session that has passed the MFA check, and the key then authenticates on its own. MFA is not possible for unattended clients.

A few sensitive endpoints can only be used with an interactive session and reject API keys, no matter which permissions the user has. This includes changing passwords, resetting MFA, and creating, listing or deleting API keys. A leaked key can therefore not be used to create new keys or to lock the user out of their account.