Preparing Zabbix: role, user and API token

This page walks through what to set up in Zabbix, version by version, so Spitfire can read it: a role, a user group, a user and an API token. All with the least rights: Spitfire changes nothing in your Zabbix and you can cut its access at any time. Adding the connection in Spitfire and its filters: Observability: Zabbix.

#What you need

Spitfire calls only these API methods:

With a password Spitfire also calls user.login and user.logout. To write findings back to Zabbix you need more rights; that section explains them. The preparation on this page opens reading only.

Zabbix permissions come from two places. This is usually your security team's first question:

• What it can see: the host group permissions of the user group. Spitfire sees only the hosts in those groups and their problems.
• What it can do: the user role (5.2 and later) or the user type (5.0). The role allows only the methods above; the UI and actions stay off.

#Find your version

The Zabbix version is shown at the bottom of every page of the UI (e.g. Zabbix 8.0.0). If you cannot reach the UI, ask the API without signing in (the first command in the try-it section).

#Steps by version

#Zabbix 7.0, 7.2 and later (8.0)

Verified: Zabbix 8.0, 2026-11-08.

1. Role: Users → User roles → Create user role.
   • Name Spitfire read-only, User type User.
   • UI elements: all off.
   • API access (at the bottom of the form, between Access to modules and Access to actions): Enabled; API methods Allow list; type hostgroup.get, host.get, problem.get, event.get into the box and press Enter after each (or pick them with Select).
   • Access to actions: all off.
   • If the section is missing, check that a User type is chosen. The Select list shows only the methods that type may use.
2. Group: Users → User groups → Create user group.
   • Group name Spitfire readers, Frontend access Disabled (the API token is not affected by it).
   • Host permissions → Add → the host group(s) to watch → Read.
   • Leave Template permissions and Problem tag filter alone. A tag filter narrows the problems seen even further.
3. User: Users → Users → Create user.
   • Username spitfire, a long random password, group Spitfire readers.
   • Permissions tab: Role Spitfire read-only. Below it the list of host groups the user reaches appears: if the group you chose is there, role and group are linked correctly.
4. API token: Users → API tokens → Create API token.
   • User spitfire, set an expiry date (e.g. 1 year).
   • The token is shown only once: copy it right away.
5. Try it: the two commands in Try it before Spitfire. If host.get returns 0, the group is missing its host permission.

The same menu paths are expected on 7.0 and 7.2; they have not been tried one to one on these versions yet.

#Zabbix 6.4

The steps are the same as on 7.x: the Users top menu and sending the token in the Authorization: Bearer header both arrived in this version. In Spitfire choose Zabbix 6.4 as the Zabbix version.

#Zabbix 6.0 and 6.2

• Role: Administration → User roles. The fields are as in step 1 on 7.x.
• Group: Administration → User groups. On 6.0 the group form has a single Permissions tab; 6.2 split it into Template permissions and Host permissions. Give Read on the host groups.
• User: Administration → Users.
• API token: Administration → General → API tokens.
• The token goes in the auth field of the request body; Spitfire does this itself when you choose Zabbix 6.0–6.2.

#Zabbix 5.4

Like 6.0: the menus are under Administration, the token goes in the auth field. 5.4 is the first version with API tokens. In Spitfire choose Zabbix 5.4.

#Zabbix 5.2

There are roles and an API method allow list (as on 6.0, under Administration), but no API token. In Spitfire choose Zabbix 5.0–5.2 and User name + password as the Sign-in.

Leave the group's Frontend access at System default. When signing in with a password, a Disabled group may refuse the sign-in (No permissions for system access); this has not been verified yet. From 5.4 on, with a token, Disabled is safe.

If you run Zabbix 5.0, see the next section.

#Zabbix 5.0 LTS

• There are no roles: on the user's Permissions tab choose Zabbix user as the User type.
• Method-level limits are not possible. The Zabbix user type already sees only the hosts it may read and cannot change the configuration. Tell your security team so: the user is not an admin and reads only the hosts of its own group.
• There are no tokens: in Spitfire choose Zabbix 5.0–5.2 and User name + password.
• Leave the group's Frontend access at System default, for the reason given on 5.2.

#Behind a front door

If your Zabbix sits behind an SSO gateway, Cloudflare Access or a reverse proxy, Spitfire's request gets stuck there. Spitfire's Zabbix client sends only the Authorization header; it cannot send the Cloudflare CF-Access-Client-Id / CF-Access-Client-Secret headers. The way that works today: open only the API path (/api_jsonrpc.php) at the gateway, for Spitfire's outgoing IP. The UI stays behind the gateway; the Zabbix token protects the API.

#Cloudflare Access

Why a separate application: Access matches the more specific path on the same host first. The application opened for the API path covers only that file; the UI stays on the existing application's e-mail or SSO policy. Adding a Bypass to the existing application opens the whole UI to that IP: do not do it.

1. Find Spitfire's outgoing IP. Run this on the machine Spitfire runs on. If the second line is empty there is no IPv6 egress.

   bashCopy

   curl -4 -s ifconfig.me; echo; curl -6 -s ifconfig.me; echo

2. Zero Trust → Access controls → Applications → Create new application. The Self-hosted and private tab, Public DNS → Continue with Self-hosted and private.

3. Destinations → Public hostnames: Subdomain zabbix, Domain your domain, Path api_jsonrpc.php (without a leading /). If Zabbix is served under a sub-path (e.g. /zabbix/api_jsonrpc.php), write the path to match. The domain list may hold names that look alike: pick carefully.

4. Access policies → Create new policy:

   • Policy Name: e.g. spitfire-bypass
   • Action: Bypass
   • Include → Selector IP ranges → value <IPv4>/32 (Enter), and <IPv6>/128 (Enter) if you have one
   • Save policy. The policy lands in the application's list as Bypass.

5. Leave the Authentication section alone: Bypass does no sign-in.

6. Details → Name: the default name may match the existing application's (e.g. zabbix); give it a telling name, e.g. zabbix-api-spitfire. Create.

7. Check:

   • From the Spitfire machine, the apiinfo.version call (the first command) returns the version: {"jsonrpc":"2.0","result":"8.0.0","id":1}.
   • From another machine the same call returns 403. The only policy in this application is Bypass, so IPs that do not match get a 403 straight away, not the sign-in page. This is expected.
   • From another machine the UI (/) redirects to the Access sign-in page (302). The UI stays protected.

Watch out: Bypassed requests do not show in the Access logs; to watch API access, look at the Zabbix audit log. If the Spitfire machine's IP changes (a new server, IPv6 switched on), the connection breaks with 403: add the new IP to the policy from step 4. Authenticated Origin Pulls is no problem, the request still comes through Cloudflare.

A Service Auth policy with a Cloudflare service token is a better way, as it is not tied to an IP, but Spitfire cannot send those headers today, so it cannot be used for now.

#Other gateways

The method is the same: skip the gateway's pre-authentication only for the /api_jsonrpc.php path and only for Spitfire's outgoing IP.

• SSO or application proxies (e.g. Okta, Azure AD App Proxy, Zscaler): a "skip pre-authentication by IP" rule for the API path.

• nginx with auth_request in front: drop the auth on the API path and limit it by IP.

  nginxCopy

  location = /api_jsonrpc.php {
      auth_request off;
      allow <Spitfire IPv4>;
      allow <Spitfire IPv6>;
      deny all;
      # your existing proxy_pass / fastcgi_pass line
  }

• IP allow list only (firewall): add Spitfire's outgoing IPv4 and IPv6 addresses.

#Try it before Spitfire

Run these from the machine Spitfire runs on; replace zabbix.example.com with your own address.

1. Version (without signing in, without a token):

   bashCopy

   curl -s -X POST https://zabbix.example.com/api_jsonrpc.php -H 'Content-Type: application/json-rpc' -d '{"jsonrpc":"2.0","method":"apiinfo.version","params":{},"id":1}'

   Right output: {"jsonrpc":"2.0","result":"8.0.0","id":1}. If HTML comes back, the address is not the Zabbix frontend or a sign-in page is answering: front door.

2. The number of hosts the token sees. 6.4 and later (Authorization: Bearer):

   bashCopy

   curl -s -X POST https://zabbix.example.com/api_jsonrpc.php -H 'Content-Type: application/json-rpc' -H 'Authorization: Bearer <token>' -d '{"jsonrpc":"2.0","method":"host.get","params":{"countOutput":true},"id":2}'

   5.4, 6.0 and 6.2 (the token in the auth field of the body):

   bashCopy

   curl -s -X POST https://zabbix.example.com/api_jsonrpc.php -H 'Content-Type: application/json-rpc' -d '{"jsonrpc":"2.0","method":"host.get","params":{"countOutput":true},"auth":"<token>","id":2}'

   5.0 and 5.2: sign in with user.login first and put the result it returns in place of <token> in the command above.

   bashCopy

   curl -s -X POST https://zabbix.example.com/api_jsonrpc.php -H 'Content-Type: application/json-rpc' -d '{"jsonrpc":"2.0","method":"user.login","params":{"user":"spitfire","password":"<password>"},"id":1}'

   Right output: {"jsonrpc":"2.0","result":"3","id":2} (a number above zero). If it is "result":"0", the group is missing its host permission. If the answer holds "error", look up the text in its data field in the common errors table.

#In Spitfire

In the Observability → Add → Zabbix dialog:

Then Save and Test the connection: it tells the Zabbix version and the number of hosts that match the filter.

#Common errors

#Undoing it

You can cut the access at any time:

1. Disable or delete the token: Users → API tokens (5.4–6.2: Administration → General → API tokens) → Disable / Delete.
2. Disable or delete the spitfire user: Users → Users (up to 6.2: Administration → Users).
3. If you like, delete the role and the group too, and remove the Bypass application from the front door.

The connection in Spitfire becomes "unreadable"; the problems in past runs stay with those runs.

#Related pages

• Observability: Zabbix
• Writing a trapper value to Zabbix
• Connection health