---
sidebar_label: Authenticate
toc_max_heading_level: 3
doc_id: f2d6d4c8-0f2c-4b8c-9a7f-6241e2b8ac1b
description: Authenticate agents with API keys using NRN-based permissions so a single agent can cover multiple accounts or resources.
keywords:
  - agent
  - authentication
  - api key
  - nrn
  - control plane
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# 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 roles **agent** (`controlplane:agent`) and **ops**. Add any extra roles the agent needs for your
  workflows (e.g., `developer`, `secrets-reader`).
1. Save the API key securely—you will pass it to the agent as `NP_API_KEY` later.

:::note
You will use this same API key when you install the agent.
:::

## 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](/docs/agent-index):

<Tabs
defaultValue="agent-nrn-list-cli"
values={[
{ label: 'CLI', value: 'agent-nrn-list-cli' },
{ label: 'cURL', value: 'agent-nrn-list-curl' },
]}>
<TabItem value="agent-nrn-list-cli">

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

</TabItem>
<TabItem value="agent-nrn-list-curl">

```bash
curl -L 'https://api.nullplatform.com/controlplane/agent?nrn=organization=1:account=2' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <token>'
```
  </TabItem>
</Tabs>


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

```json
{
  "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.

## Next steps

Now that you created an API key, you can jump to [installing the agent](installation.md).