Connection Key
The connection key is the secret that agents present when they register with your UTMStack v12 server. The install commands shown in Integrations include it automatically. This page explains how to view, copy and regenerate it.
Who can use this page
You need the Administrator role. On a multi-tenant licence each tenant has its own connection key, and agents installed with it register in that tenant.
Where the key is used
The key is part of the install commands that UTMStack shows in Configure > Integrations for:
The Windows, Linux and macOS agents.
The UTMStack Forwarder.
The IBM AS/400 collector.
The UTMStack self-monitoring collector.
You do not usually need to copy the key by hand: the install command on the integration page already contains it.
The key is not used to sign in to the web interface or the API. For the API, use an API key (see API Keys).
View or copy the key
Go to Configure > Settings > Connection Key.
Check Status. Active means agents can register with the key. Agent-manager unavailable means UTMStack could not reach the service that manages agents; click Retry after a moment.
Click Show key to see it, or Copy to copy it.
Treat the key as a password. Anyone who has it can register a machine with your server. Do not store it in source control; keep it in a secret manager and pass it to your installation scripts from there.
Regenerate the key
Regenerate the key if it may have leaked, or as part of a regular rotation (for example every 90 days).
- 1
Open the page
Go to Configure > Settings > Connection Key.
- 2
Regenerate
Click Regenerate connection key, then Yes, regenerate.
- 3
Update your install scripts
New installations need the new key. The install commands in Integrations show the new key at once. Update any scripts or software-deployment packages that contain the old key.
Agents that are already registered keep working after you regenerate the key. There is no undo: the old key cannot be restored.
Troubleshooting
| What you see | Cause | Fix |
|---|---|---|
| Status Agent-manager unavailable | The backend cannot reach the agent manager service | Click Retry. If it stays, check the service on the server with docker service ps utmstack_agentmanager and docker service logs --tail 100 utmstack_agentmanager. |
| New agent installations fail to register after you regenerated the key | The install command or script still contains the old key | Copy the install command again from Integrations, or update the key in your script. |
| An agent registers in the wrong tenant | The install command was copied while working in another tenant | Copy the install command from the tenant the agent belongs to. |
| You cannot see the page in the menu, or opening it by its address shows Agent-manager unavailable | You do not have the Administrator role: the key is shown only to that role, whatever permissions a custom role has | Ask an administrator. |
On a multi-tenant server, see Multi-Tenancy Overview for how tenants and agents relate.