Agents

Agents are accounts that do not belong to a person and cannot sign in. You use them to create access tokens for the Netzilo API, so scripts, infrastructure-as-code and integrations keep working when an employee leaves. In older versions of the dashboard, agents were called service users.

Agents are under Team > Agents.

Use an agent's token for:

  • Automated scripts and infrastructure-as-code tools such as Ansible or Terraform that configure your Netzilo network.
  • Third-party integrations that need your account's data without anyone's personal account.
  • Command-line tools such as curl.

Create an agent

  1. Go to Team > Agents and click Create Agent.

The Agents page under Team with the text Use agents to create API tokens and avoid losing automated access, a Create Agent button, and one agent named ci-deployer with the role Admin and the status Active

  1. Fill in the dialog and click Create Agent:

The Create Agent dialog with the text Agents are non-login users that are not associated with any specific person, the name automation and the role Admin

FieldWhat to enter
NameA name that says what the agent is for, such as automation or reporting
RoleUser to read, Admin to read and change

An agent with the User role reads only what a regular user may read. It cannot read the administrator-only parts of the API, such as groups, posture checks, DNS, events, reports, settings, integrations and the Edge objects. Diagnosis and most automation need an Admin agent.

Keep agents to a minimum and give each the least role its job needs. The role, not the token, decides what a token can do.

Create an access token

  1. Under Team > Agents, click the agent.
  2. Under Access Tokens, click Create Access Token.

The page of the agent ci-deployer under Team, Agents, with Name, Status and MFA, the User Role Admin, and an Access Tokens list with one token, its expiry date, last use, a copy button and Delete

  1. Fill in the dialog and click Create Token:

The Create Access Token dialog with the text Use this token to access Netzilo's public API, the name ci-2026-10 and Expires in 90 days

FieldWhat to enter
NameA name you will recognise later, such as ci-2026-10
Expires inBetween 1 and 365 days
  1. The dialog Access token created successfully! shows the token once. Click Copy to clipboard and store it in a secret store. Netzilo keeps only a hash of it, so it cannot show it again.

You cannot change a token after you create it. Create a new one instead.

Your own tokens are under the user menu, Profile Settings > Access Tokens, see Profile Settings. A token there acts with your role, and stops working when your account is blocked or deleted. Administrators can also create tokens on a regular user's page, see Users. No one can create a token for another admin or for the owner.

The AI Gateway token that the Workplace creates, and the (MCP) tokens of applications such as Claude Desktop, only identify a user to AI gateways. They cannot be used with the API.

Use the token

Send the token in the Authorization header. The API is at https://srv.netzilo.com/api on Netzilo Cloud, and at https://<your-domain>/api on a self-hosted server.

List users with an access token

curl https://srv.netzilo.com/api/users \
  -H "Authorization: Token nzl_..."

Authorization: Bearer nzl_... is accepted too. Every request runs with the role of the token's owner. See the API reference for the endpoints.

Things to design around:

  • The API has no version prefix and no idempotency keys. A retried create can create a duplicate, so check before you create.
  • Only /api/events/paginated paginates. Every other list returns everything.
  • A PUT replaces the whole object. Read it first, change the field, and write it back.
  • Field validation errors return HTTP 422, not 400.

Rotate a token

Create the new token before you delete the old one:

Rotate the token of the agent named automation

export NZ_URL=https://srv.netzilo.com/api
export NZ_TOKEN=nzl_...   # the current token
nz() { curl -sS -H "Authorization: Token $NZ_TOKEN" -H 'Content-Type: application/json' "$NZ_URL$1" "${@:2}"; }

AGENT=$(nz "/users?service_user=true" | jq -r '.[] | select(.name=="automation") | .id')
nz /users/$AGENT/tokens -X POST -d '{"name":"ci-'$(date +%Y%m)'","expires_in":90}' | jq -r .plain_token
nz /users/$AGENT/tokens | jq '.[] | {id,name,expiration_date,last_used}'
# store the new token, then delete the old one:
# nz /users/$AGENT/tokens/<old token id> -X DELETE

Nothing warns you before a token expires. Put its expiry date in your calendar or your secret store.

Delete an agent

Click Delete on the agent's row under Team > Agents. Its tokens stop working.

Troubleshooting

The API answers 401 token invalid. The token is mistyped, expired or deleted. The API cannot tell which. Create a new token.

The API answers no valid authentication provided. The Authorization header is missing or malformed. Send Authorization: Token nzl_....

The API says the user has no access or is blocked. The token's owner is blocked.

The API answers 403 only users with admin power can perform this operation. The agent has the User role. Change it to Admin on the agent's page, or use another agent.

Creating an agent fails with maximum number of users reached. The Free plan allows 5 users, agents included.

A token works for some paths and is refused for others with token scope "mcp". It is an AI Gateway or (MCP) token. Create a token on an agent instead.