Shared secrets and access grants

Open Manage → Secrets to store API keys, passwords, unencrypted SSH private keys or text credentials. Values are encrypted at rest. After saving, the portal returns metadata only; it cannot reveal the stored value. Keep credentials out of names, descriptions, targets and query text.

secrets:read allows metadata and grant inspection. secrets:manage permits creation, rotation, revocation and deletion. secrets:grant separately controls approval or revocation of use by a check and agent.

Prepare the agent

Shared delivery requires a private enrolled agent started with -secrets-remote and its configuration signing key, using an HTTPS configuration endpoint. The deployment must have the shared encryption keyring configured on the portal and control services. Participating agents must support the current signed grant protocol and short execution leases.

Without shared mode, existing agent-local file and environment secret providers still apply. In shared mode, missing secrets do not fall back to local values. Public agents cannot receive these credentials.

Approve one exact use

1. Create the secret and select it in the check’s Authentication secret field.
2. Assign the check to the private agent that will execute it.
3. Open the secret’s Access control, enter the check and agent IDs, and review the destination and complete parameters.
4. Approve that scope. Without a matching grant, the agent cannot receive the value.

Each grant binds the secret, check, private agent, destination, protocol, address family and complete parameters. Changing a target, username, header, SSH command or other parameter invalidates that scope. Review and approve the revised use. Restoring an exactly matching previously approved scope can reuse its surviving grant.

The picker lists secret names and descriptions, never secret values. No secret clears authentication. Use an agent-local secret lets you enter a name already configured on the agent; it does not change the agent’s secret provider or enable a local fallback in shared mode. Missing, revoked or inaccessible references are preserved when editing so you can replace or clear them deliberately.

API Flow, browser and SNMP checks expose an agent-local reference field because their shared delivery is not supported. A reference is a lookup name, not the password or token itself. Selecting a saved secret does not create its access grant.

Supported destinations

• HTTP requires HTTPS, certificate verification, TLS 1.2 or newer and explicit max_redirects: 0. A TLS-name override must match the destination.
• SSH, Remote Host Metrics and SFTP require a pinned, verified server key, including when logging in with a password. SSH forms offer saved password or private-key secret pickers. See Remote Host Metrics. SMB uses agent-local credentials.
• Database checks require verified TLS. SIP requires TLS.
• gRPC, email, LDAP and MQTT require verified TLS, including mandatory STARTTLS where the protocol supports it. WebSocket requires WSS; RADIUS requires RadSec TLS.
• Throughput and RTP responder tokens require an HTTPS control endpoint.

Scripts, browser credential maps and unsupported check types cannot use shared delivery. See service checks for credential formats and protocol-specific restrictions.

Rotate, revoke and delete

Rotation replaces the value and causes connected agents to reload affected checks on their next configuration poll. Concurrent edits require a fresh revision. Rotating a revoked secret does not restore removed grants.

Revoke secret removes all its grants. Revoke grant removes one approved check/agent use. Upgraded agents stop affected checks on their next successful poll or when the existing two-minute lease expires, including while offline. Remote operations already accepted by the destination may still have effects. Restarting a shared-secret check requires fresh service access.

RouteSpear rotation and revocation do not revoke credentials at the destination provider. Delete is refused while any check, including a disabled check, references the secret.

The control plane and authorized agent process can decrypt delivered values. Use agent-local credentials when the control plane must never hold them, and restrict credentials to the operations their checks need.