Sometimes it is more convenient to hand management to a program than to click buttons in a browser: another agent, your script, or a system that watches spending. For that Proxy Agent has a dedicated surface at /api/agent/*. Through it you can do nearly everything the administrator does in the interface — without opening anything in a browser.
Why you would want it
The usual pattern: an agent is given only your server’s address and the management key, and it creates the models, channels and access keys itself, then reads the logs and the spending. The person is left to check the result, not to repeat the same actions by hand.
It is also handy for one-off tasks — moving a dozen access keys to a new server, or creating models from a spreadsheet list.
The management key
Access is closed by the management key. The key is passed in the X-API-Key header, and the PROXYAGENT_API_KEY environment variable stores not the key itself but its irreversible hash (SHA-256, written lowercase). The original key cannot be recovered from the variables file.
- Variable not set — the surface answers “disabled” (503), and everything else on the server keeps working as usual.
- Key does not match — the answer is “unauthorized” (401).
- Failed attempts are written to the log together with the caller’s address. The key and its hash never reach the log.
Keep the management key secret: it opens exactly what the administrator sign-in opens — the whole configuration of the product.
Self-documentation
There is no separate manual for this surface — its documentation is built into the surface itself. The GET /api/agent request returns a description: how to sign in, which concepts are used, what happens to secrets, and the full list of addresses with their fields, replies and possible errors. It also carries a step-by-step recipe: create an access key, make a request to a model through it, read the log.
So it is enough for an agent to know the address and the key — it reads the rest by itself. The list of addresses and the description always match what the surface can really do.
What can be done
- Models and channels — create, edit, clone, enable and disable, check the connection to the vendor, and preview the servers of a Happ subscription link before the channel is saved. Everything the Models & Prices and Providers sections do.
- Access keys — create with spending limits, reissue, change the limits and the lists of allowed models and channels, enable and delete. The ready key is given out exactly once.
- Logs and analytics — read the request log, the proxy service log and every analytics report, including the ClickHouse delivery state and the backfill of missed days.
- Secret hiding — maintain the rules, try them “dry” on examples, and read the leak reports.
- Settings — read and write the values just like in the “Settings” window — the result lands in the same configuration files.
- State — see the license status and the “Dashboard” summary.
A one-time sign-in code for the browser
Sometimes a program needs to open the interface for a person. The administrator password is not needed for that: the POST /api/agent/session request issues a one-time code valid for 5 minutes. The person enters it at sign-in, the code works once and yields an ordinary 90-day administrator session.
That way the agent never needs to store your password — it only issues a single-use pass. After the first use, or once the five minutes pass, the code becomes invalid.
What stays closed
Secrets cannot be read — not in the interface, not over the API. Vendor keys, channel passwords and VPN private keys show the same masks as in the browser: writing a new secret is possible, reading the old one is not. The ready access key is shown once at creation or reissue; afterwards only the last characters are visible.
More about where the secrets live — in the Access & Security section.
What this surface does not do
- It does not replace the administrator password. It cannot issue an ordinary browser login — only a one-time code. The password itself is still set with environment variables.
- It does not open secrets. Keys and passwords stay masked.
- It does not replace the license. Configuration and management can be handled without a license key, but no traffic passes through the proxy without one. The surface itself is not gated by the license.
- It does not mix with ordinary access. The management key will not work for requests to the models, and an access key will not work for management.
Replies and errors
All requests are synchronous: the reply arrives at once, there are no long operations to wait for. Connection checks are quick probes that answer with success or failure.
Errors come uniformly: a short kind and a text with the reason. The kinds are the usual ones — an error in the request, object not found, a conflict (that name is already taken, or the object is still in use). The texts are in English: this is a technical surface for programs, not a section for humans.
Next: how the file-based configuration is organized — in the File Configuration section.