Credentials

The agent connects to each monitored host as a user you control. Credentials are managed in the Luumen UI, either per-host or as a single default set inherited by every host that doesn’t override. This page covers the credential patterns Luumen supports and when to use each. For Vault-managed credentials, see Vault integration. For the agent’s own permissions on the Patch server and on each host, see Prerequisites.

​

Default credentials

Most environments have one credential set that works against the bulk of the fleet — typically a service account and an SSH key deployed by configuration management. Set those once as the workspace’s default credentials in the Luumen UI, and every host you add inherits them automatically unless you specify otherwise. The default credential set holds:

• A username.
• One of: an SSH private key (Linux) or a password (Linux or Windows).

Setting defaults first is the right order of operations. By the time you start adding hosts, the form already offers “Use default credentials” as the easy choice for most rows.

​

Per-host credentials

A host can override the default and use its own credentials when needed. Use per-host credentials when:

• A specific host runs a different OS that requires different auth (e.g., a Windows host in a Linux fleet).
• A host has its own service account.
• A host hasn’t been onboarded to your standard credential rotation yet.

In the Add host form (or when editing an existing host), pick Use specific credentials for this host instead of Use default credentials and provide a username plus key or password.

​

SSH keys

The recommended pattern for Linux hosts.

1. Generate a keypair (or use an existing one your team manages).
2. Deploy the public key to the service-user’s ~/.ssh/authorized_keys on each target host.
3. In the Luumen UI, paste the private key into the credentials form, or upload it as a file.

Luumen stores the key encrypted at rest. Rotating the key is a UI operation — replace the value, save, and the agent uses the new key on its next run.

​

Passwords

For Windows hosts and Linux hosts where keys aren’t practical:

• Enter the password directly in the UI credentials form, or
• Reference a secret stored in HashiCorp Vault — see Vault integration.

​

Authentication mode by platform

WinRM key-based authentication is not currently supported.

​

Integration credentials

Some integrations require their own credentials (for example, SAP BTP, ServiceNow, or an observability provider). These are configured in the relevant integration’s settings rather than on individual hosts. See Integrations.

​

Rotation

To rotate a credential:

• Default credentials: update the default in the UI. The change applies to every host inheriting it on the next agent run.
• Per-host credentials: edit the host and update its credentials. Same cycle — picks up on the next run.
• Vault references: rotate the secret in Vault. The agent picks up the new value on its next run with no Luumen UI change required.

If a rotation leaves a window where the new credential isn’t yet on every target host, the agent will report connection errors for any host it can’t authenticate against. Those hosts appear with a yellow warning icon in the UI until the next successful run resolves them.

​

Verifying a credential works

If a host shows as disconnected or with a warning icon after a run:

1. From the Patch server, attempt a manual SSH or WinRM session using the same username and key/password configured in the UI.
2. If that fails, fix the credential at the source (key permissions, password value, allowed users on the target) before assuming Luumen is misconfigured.
3. If a manual session succeeds but the agent still fails, escape or simplify any special characters in the password and try again.

See Verifying capture and the credentials section of Troubleshooting for more.