UTMSTACK logoUTMSTACK logo
AdministrationAPI Keys

API Keys

API keys let scripts, other tools and AI assistants use the UTMStack v12 API (application programming interface) without a person signing in. A key acts as the user who created it, with that user's roles and tenant. API keys need an Enterprise licence.

Before you start

  • The server needs an Enterprise licence. On Community, the page shows "API keys are an Enterprise feature", and requests made with a key are refused. See License and Editions.

  • Creating, rotating, editing and deleting keys needs the apikey.write permission. Of the built-in roles, only Administrator has it. Listing your keys needs apikey.read, which all built-in roles have.

  • Each user sees and manages only their own keys.

  • Users with a custom role that includes apikey.write but not the Administrator role do not see the Settings menu. They open the page at https://<your-server>/settings/api-keys.

How a key's rights work

A key has no rights of its own. Every request made with it is treated as a request from the user who created it:

  • It has exactly the permissions of that user's current roles. If you change the user's roles, the key changes too.

  • It works in that user's tenant only.

  • If the user is deactivated, all their keys stop working at once.

A key carries all of its owner's rights. For an integration or automation, prefer a key owned by a dedicated account created for that tool, rather than a person's own account. You can then manage the tool's access, and see its actions in the App Audit Logs, separately from any person.

Create a key

  1. 1

    Open API Keys

    Go to Configure > Settings > API Keys and click New API key.

  2. 2

    Fill in the fields

    FieldWhat to enter
    NameA name that says what the key is for, for example ci-pipeline. It must be unique among your keys.
    Allowed IPsThe addresses allowed to use the key, separated by commas. Ranges in CIDR notation (for example 192.0.2.0/24) are accepted. Leave empty to allow any address.
    ExpiresThe date the key stops working. Leave empty for a key that never expires.
    The New API key dialog with the Name, Allowed IPs and Expires fields, a reminder that the secret is shown only once, and the Create key button
  3. 3

    Create the key

    Click Create key.

  4. 4

    Copy the secret

    The API key created window shows the secret. Click Copy and store it in a safe place, such as a password manager or secret store, then click Done.

The secret is shown only once. UTMStack cannot show it again. If you lose it, rotate the key to get a new secret.

Use a key

Send the secret in the Utm-Api-Key header of each request. For example, this request returns the number of open alerts:

curl -sk "https://<your-server>/api/v1/utm-alerts/count-open-alerts" 
  -H "Utm-Api-Key: <your-api-key>"

The -k option skips certificate checks; leave it out if your server has a trusted SSL certificate.

On a multi-tenant licence, send requests to the address of the key owner's tenant.

For the full API and other ways to sign in, see Authentication and API Keys. To connect an AI assistant with a key, see MCP Server.

Manage keys

The API Keys page listing keys with their allowed IPs, created, last rotated and expiry dates, status, and the rotate, edit and delete buttons

The list shows each key's Name, Allowed IPs, Created, Last rotated, Expires and Status:

StatusMeaning
ActiveThe key works.
ExpiringThe key expires within 7 days.
ExpiredThe key no longer works.

Actions on each key:

ActionWhat it does
RotateIssues a new secret. The old secret stops working at once. The new secret is shown once. If the key has an expiry date, it moves forward so the key keeps the same lifetime from the moment of rotation.
EditChanges the name, allowed IPs or expiry date. The secret stays the same.
DeleteRemoves the key. Any tool using it loses access at once. This cannot be undone.

Use the search box to find a key by name or allowed IP, and Refresh to reload the list.

Good practice

  • Create one key per tool, so you can rotate or delete it without affecting other tools.

  • Set an expiry date and rotate keys regularly. The list marks keys that expire within 7 days as Expiring.

  • When a person leaves, deactivate their user account; this stops all their keys at once.

  • Administrators cannot see or delete other users' keys. To stop the keys of another user, deactivate that user.

Troubleshooting

Message or answerCauseFix
"An API key with that name already exists"You already have a key with that nameChoose another name.
"operation failed" when creating a keyThe name is longer than 255 characters, or another unexpected problemUse a shorter name; otherwise check docker service logs utmstack_backend.
"Key created, but the secret could not be issued. Use Rotate to get one."The key was saved but its secret was not createdClick Rotate on the key to get a secret.
"API keys require the Enterprise edition" when you create or rotate a key, or every request with a key is refused with 401No valid Enterprise licenceInstall the licence. See License and Editions.
Requests with a key answer 401The secret is wrong, was rotated, the key expired or was deleted, the request came from an address not in Allowed IPs, or the owner was deactivatedCheck the key's status, rotate it, or use a key of an active user.
Requests answer 403 for one action but work for othersThe key owner's roles lack the permission for that actionGive the owner a role with the permission (see Roles and Permissions).
On a multi-tenant server, a key works on one address but not anotherA key works only on its owner's tenant addressSend requests to the address of the owner's tenant.