Skip to main content

Authenticate the agent

Agents authenticate with API keys. When the key includes the Agent role, the platform looks at every NRN permission on that key and builds the agent’s nrns array from them.

This lets one agent serve multiple resources (accounts, namespaces, applications, or any NRN you include) without extra configuration.

Create an agent API key​

  1. Go to Platform settings > API keys and click + New API key.
  2. Select each resource (NRN) the agent should serve. You can choose a single account or multiple NRNs across your hierarchy.
  3. Assign the Agent role (controlplane:agent). Add any extra roles the agent needs for your workflows (e.g., developer, ops, secrets-reader).
  4. Save the API key securely—you will pass it to the agent as NP_API_KEY.

How NRN assignment works​

  1. The agent starts with NP_API_KEY.
  2. The nullplatform reads the key’s permissions with the controlplane:agent role and builds the agent’s nrns array.
  3. The agent registers with those NRNs and can respond to work for any matching scope.

💡 Want one agent to cover multiple resources? Add all relevant NRNs to the API key. No extra agent configuration is needed.

Verify the agent’s NRNs​

List agents and filter by NRN using the Control plane API:

np agent list \
--nrn organization=1:account=2

The response includes the agent’s nrns array, for example:

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "name": "my-agent-name",
  "nrns": ["organization=1:account=2", "organization=1:account=2:namespace=3"],
  "status": "active",
  "capabilities": []
}

Migrating existing agents​

  • No downtime: Agents using older account-level keys keep working. Those keys infer a default NRN from the account data.
  • Migrate one agent at a time: Edit or create a new key with controlplane:agent for the NRNs you need, set it as NP_API_KEY, and restart that agent.
  • Verify after restart: Call the agent list API (with optional nrn filter) and confirm the agent shows the expected nrns array.
  • Roll back easily: If something looks off, switch back to the previous key and restart the agent.

For installation steps, see Install the agent. If you need to refresh sources after changing keys, see Refresh agent sources.