Job & Plugin: Settings Keys

Audience: Integrators configuring appsettings.json or reading runtime settings via GET /api/PluginSettings/{pluginName}.

This page lists the settings keys most relevant to custom job and plugin integrations. For the narrative explanation of how to call Plugin Settings from inside a running binary, see the Overview page. For the full Plugin Settings API endpoint reference, see the HTTP Reference.

How Settings Are Merged

Effective settings for a component come from three sources, applied in this order of precedence:

1. Unified storage — values applied by policy or written via PUT /api/PluginSettings/{pluginName}/{settingName}. These override everything below.

2. Plugin JSON on disk — the Plugins/{PluginId}.json file for managed plugins, or system-level JSON files for agent-wide settings.

3. System defaults — built-in defaults compiled into the agent.

Always read effective settings via GET /api/PluginSettings/{pluginName} rather than parsing JSON files on disk directly. The file on disk may not reflect policy overrides in unified storage.

Application-Wide Settings (appsettings.json)

These keys live in the Settings section of appsettings.json next to the agent service executable. Changes require a service restart to take effect.

Key

Type

Common Default

Purpose

KestrelHttpsPort	integer	6889	HTTPS port for the local API. Used to construct KeeperApiBaseUrl in job argument substitution.
KestrelHttpPort	integer	6888	HTTP port for the local API. Prefer HTTPS for all sensitive operations.
AlternativeSignatures	string array	—	Authenticode certificate thumbprints trusted for process authentication. Add your binary's signing certificate thumbprint here when MQTT or Plugin-tier HTTPS access must work outside a job-launched context.
AllowedNonAdminExecutables	string array	—	Executable base names (no path, no .exe) permitted to pass process authentication in a user session when the process owner is not an administrator. Only relevant for ExecutionType: User or UserDesktop tasks. Not required for Service tasks.
RepositoryPath	string	varies	Storage directory for the agent's configuration repository.
PluginPath	string	Plugins	Plugin root folder name or path, relative to the agent root.

Example Settings block showing the keys most commonly configured during integration:

{
  "Settings": {
    "KestrelHttpsPort": 6889,
    "KestrelHttpPort": 6888,
    "AlternativeSignatures": [
      "A1B2C3D4E5F6789012345678901234567890ABCD"
    ],
    "AllowedNonAdminExecutables": [
      "MyTool"
    ]
  }
}

To get the Authenticode thumbprint of a signed Windows binary:

Get-AuthenticodeSignature -FilePath "C:\Path\To\MyTool.exe" |
  Select-Object -ExpandProperty SignerCertificate |
  Select-Object -ExpandProperty Thumbprint

Use the result as a 40-character hex string with no spaces.

MQTT Broker Settings (MqttBrokerSettings)

These keys configure the local MQTT broker. They live under MqttBrokerSettings in appsettings.json and are surfaced via Plugin Settings as broker.host and broker.port.

Key

Typical Default

Purpose

IpAddress	127.0.0.1	Broker bind and connect address. Loopback in standard deployments.
Port	8675	Broker TCP port. The broker uses TLS — this is the encrypted port, not a plain TCP port.

Do not hardcode these values in your binary. Read them at runtime from Plugin Settings so your binary tracks any configuration changes an administrator makes:

GET {KeeperApiBaseUrl}/api/PluginSettings/KeeperPrivilegeManager

The response includes broker.host and broker.port as string values reflecting the effective MqttBrokerSettings in use by the running agent. See the Overview page for a complete code example.

Keys Read at Runtime via Plugin Settings

These are the keys a custom job task or plugin typically reads from GET /api/PluginSettings/KeeperPrivilegeManager at startup. The call requires Plugin-tier authentication — it must come from a process the agent launched.

Key

Source Setting

Use

broker.host	MqttBrokerSettings:IpAddress	MQTT broker hostname or IP for TLS connection
broker.port	MqttBrokerSettings:Port	MQTT broker port

Other keys may appear in the response depending on agent version and policy configuration. Parse only what your binary needs.

For plugin-scoped settings specific to your component, use your plugin's own ID:

GET {KeeperApiBaseUrl}/api/PluginSettings/{YourPluginId}

This returns settings stored under your plugin's namespace, merged with system defaults. Use this for any configuration your plugin needs that is separate from the system-wide broker settings.

Last Known Good (ConfigurationLkg)

Key

Type

Effect

ConfigurationLkg:Enabled	boolean	When true, the agent maintains an encrypted reference copy of each job's JSON and watches the Jobs/ directory for drift. Hand-edited job files may be restored from the reference copy. Use the API or a JobUpdate policy to write jobs reliably when this is enabled.

Confirm whether Last Known Good is enabled in your deployment before choosing a job deployment method. See Part 3 of the Custom Job Integration Guide for the full explanation.

Applying Changes

Change type

How to apply

appsettings.json edits (AlternativeSignatures, ports, broker settings)	Restart the agent service
Plugin Settings via PUT /api/PluginSettings/{id}/{key}	Takes effect immediately for subsequent reads; the plugin may need to re-read settings or restart to pick up the change depending on how it caches configuration
Policy-delivered settings	Applied when the Configuration Policy Processor runs on the endpoint
Plugin JSON on disk	Effective after agent restart, or after POST /api/PluginSettings/{id}/revert re-imports the file into unified storage