Authentication

Every request to the Netzilo API carries a token in the Authorization header. For scripts and automation, use a personal access token of an Agent: a non-login user that belongs to no specific person. You can also use your own access token, or an OIDC access token from the identity provider.

Base URL

ServerBase URL
Netzilo Cloudhttps://srv.netzilo.com/api
Self-hosted Netzilo Serverhttps://<your domain>/api, for example https://go.example.com/api

A request without a token answers 401, which proves you reached a live server:

curl -sS -o /dev/null -w '%{http_code}\n' https://srv.netzilo.com/api/users

Create a token for automation

Agents keep working when an employee leaves, cannot sign in, and are not counted as billed users. Their role decides what their tokens may do: User can only read, Admin can read and write.

  1. In the dashboard, go to Team > Agents and click Create Agent.
  2. Enter a name, for example automation, choose the role, and click Create Agent.

The Create Agent dialog with the name automation and the role Admin

  1. Open the Agent, and under Access Tokens click Create Access Token.
  2. Enter a name and an expiry between 1 and 365 days, and click Create Token.

The page of the Agent ci-deployer with the role Admin and its Access Tokens list, and the Create Access Token button

  1. Copy the token. It is shown only once.

Tokens start with nzl_. Keep them in a secret store or an environment variable, never in a script or a ticket.

Using personal access tokens

Send the token with the Token scheme:

curl -sS https://srv.netzilo.com/api/peers \
  -H 'Accept: application/json' \
  -H 'Authorization: Token nzl_...'

Authorization: Bearer nzl_... is accepted too. On a self-hosted server, use your own base URL.

Your own token. Every user, including regular users, can create tokens for themselves: open the user menu, choose Profile Settings, and use Create Access Token under Access Tokens. A token acts with your role and everything you can reach, and its use is recorded as you.

The own user page of Alice Morgan opened from Profile Settings, with the Access Tokens list and the Create Access Token button

An OIDC access token. A script that already signs in to your identity provider can send its access token as Authorization: Bearer <JWT>, as the dashboard does.

What a token may do

  • A token carries its owner's role. Regular users can read and manage their own tokens; admins, owners and Admin Agents can also write.
  • Some paths are for admins only, also for reading: for example groups, posture checks, DNS, events, reports, Edge and the account's integrations.
  • Some paths answer every user with that user's own view, for example GET /api/users/current/published-apps.
  • The AI Gateway token that the Workplace creates for Agentic Access only identifies its user to AI gateways. It cannot be used for scripts; create an ordinary token for those.

There is no other way to narrow a token. Least privilege means choosing the owner's role.

Revoke a token

Delete the token on its owner's page, under Access Tokens. Tokens expire on the date you set, between 1 and 365 days after creation, and nothing warns you before. Plan rotation: create the new token, switch your scripts to it, then delete the old one.

When authentication fails

AnswerMeaning
401 with token invalidThe token is wrong, expired or deleted. All three look the same
401 with no valid authentication providedThe Authorization header is missing or unreadable
A message that the user has no access to the API or is blockedThe token's owner is blocked
403The token is valid, but its owner's role does not allow this request

See Errors for all status codes.

Was this page helpful?

© Copyright 2026. All rights reserved.