The JSON API

Authentication and roles

API calls use the same accounts and the same three roles as the GUI. A viewer token cannot write. An operator token cannot manage users. Every write is recorded in the audit log with the account that made it, exactly as a click would be.

What people use it for

• Driving a blocklist from something else, by pushing key value pairs into a map.
• Adding and removing pool members as part of a deployment, then applying.
• Draining a backend before a release and putting it back afterwards.
• Reading health and utilization into whatever you already use for monitoring.
• Exporting the audit log into a log analysis system.

Writes still need an apply

This trips people up the first time. A write over the API saves, exactly like a save in the GUI. It does not go live until an apply, which is also an API call. That is deliberate: a script that changes five things should apply once at the end, not five times, and it should be able to check what it is about to do first.

Tokens and the browser

Browser sessions carry a CSRF token, and a write with no token or a forged one is refused. There is a check in the test suite for exactly that. If you are writing a client, use a token rather than trying to reuse a browser session.

Reload rate is the real limit

Common questions