API keys

An agent proves which organization it belongs to with an API key. A key is the organization, for the agent presenting it.

Create

In the organization’s API keys section. Admins create keys — or only owners, if the security policy says so.

Property	Default	Notes
Name	—	What the key is for: “Head office agent”
Single agent	On	Bound to the first agent that registers with it, refused to every other
Expiry	One year	At most two years

The key, nk_ followed by 256 random bits, is shown once. Infrality keeps only its SHA-256; nobody can show it to you again. What the list shows beside each key is a separately generated label, not part of the key.

At most 25 active keys per organization.

Single-agent keys

A single-agent key is claimed by the first agent that registers with it. After that, any other agent presenting it is refused — including the same machine under a new hostname after a rebuild. That is either a rebuild an admin should confirm or a credential that walked to another host; in both cases, issue a new key.

Deleting an agent revokes the keys bound to it.

An organization-wide key (single agent off) can register any number of agents. Use it only where you deploy many agents from one image and rotate it on a schedule.

Rotate

1. Create a new key.
2. Put it in the agent’s config.yaml (or INFRALITY_INGESTOR_API_KEY) and restart the agent.
3. Delete the old key once the agent shows online with the new one.

Restrict where keys are used from

The security policy can accept keys only from given address ranges — the public addresses your sites leave by. A key presented from elsewhere is refused with This API key is not accepted from this machine’s address. See security policy.

If a key leaks

Delete it in the API keys section. The agent using it stops at its next registration or reconnection; issue it a new key.