The IntelliTrend API Guard acts as an API reverse-proxy/gateway for a Zabbix web frontend.
The main purpose is to allow public access to the Zabbix API without exposing the entire web frontend.
API access is controlled with bearer tokens, which are separate from the Zabbix API tokens.
The API Guard works by requiring every incoming HTTP(S) request to contain a valid bearer token in the X-API-GUARD: Bearer … header.
When a request arrives, the API Guard looks up that token in its configuration file. The token is directly mapped to a destination URL. Because the token already determines where the request must go, the URL path supplied by the client is ignored – it can be “/” or any arbitrary string.
After the token is validated, the API Guard forwards the request exactly as it was received (same HTTP method, headers, and body) to the destination URL associated with the token, and then returns the destination’s response unchanged.
Any incoming requests without the X-API-GUARD header set, or with an invalid token, will be denied with an 401 Unauthorized response.
Targets are defined in a YAML file that is passed as parameter --targets. Here is an example for a single Zabbix target:
# Example of a target config for one Zabbix target
targets:
zabbix:
# the URL to your Zabbix frontend API, including "api_jsonrpc.php"
url: https://zabbix.example.com/api_jsonrpc.php
# optional - path to a CA PEM file that was used to sign the Zabbix frontend's certificate
caPath: "/etc/ssl/prod_ca.crt"
# optional - set this to true to ignore certificate errors on the Zabbix frontend entirely
# skipVerify: true
tokens:
# List of tokens assigned to this Zabbix server. API clients must include one of these
# in the HTTP header as "X-API-GUARD: Bearer ...".
# Each token can be any string, e.g. hex strings, base64 or just some text.
- 0D6640E54634758727B0DD4C9D9F6009
- EjNcAhScADha1pbkNYyzVg==
- mytokenIt is also possible to define multiple Zabbix targets. The token decides what Zabbix target should receive the request. As a result, it's important that each token is uniquely assigned to one target only. The API Guard will treat duplicate tokens as errors.
Here is an example for a multi-target config:
# Example of a target config for multiple Zabbix targets
targets:
# development server
zabbixDev:
# the URL to your Zabbix frontend API, including "api_jsonrpc.php"
url: https://zabbix-dev.example.com/api_jsonrpc.php
# optional - path to a CA PEM file that was used to sign the Zabbix frontend's certificate
caPath: "/etc/ssl/dev_ca.crt"
# optional - set this to true to ignore certificate errors on the Zabbix frontend entirely
# skipVerify: true
tokens:
# List of tokens assigned to this Zabbix server. API clients must include one of these
# in the HTTP header as "X-API-GUARD: Bearer ...".
# Each token can be any string, e.g. hex strings, base64 or just some text.
#
# Note: Tokens must be unique and can't be reused between servers!
#
# Example for 128 bit hex tokens.
#
# Generate more with this command:
# hexdump -vn16 -e'4/4 "%08X" 1 "\n"' /dev/urandom
- 0D6640E54634758727B0DD4C9D9F6009
- 79A17B763BF5DEDD95335E43AE6D6D69
- 900963542AC3BA0F3E9190D8CC8B8E24
- mytoken
# production server
zabbixProd:
# the URL to your Zabbix frontend API, including "api_jsonrpc.php"
url: https://zabbix.example.com/api_jsonrpc.php
# optional - path to a CA PEM file that was used to sign the Zabbix frontend's certificate
caPath: "/etc/ssl/prod_ca.crt"
# optional - set this to true to ignore certificate errors on the Zabbix frontend entirely
# skipVerify: true
tokens:
# List of tokens assigned to this Zabbix server. API clients must include one of these
# in the HTTP header as "X-API-GUARD: Bearer ...".
# Each token can be any string, e.g. hex strings, base64 or just some text.
#
# Note: Tokens must be unique and can't be reused between servers!
#
# Example for 512 bit tokens encoded with base64.
#
# Generate more with this command:
# dd if=/dev/urandom bs=64 count=1 2> /dev/zero | base64 -w0; echo
- pCusUADrlVQhsteSRI0GeslEmNtr7VtErTHAk5ZshL8LqeeCQOt+Ethq1aTDHEe50xjAHrNTKmLpNKwd9Zg6GQ==
- nCLfTzZaFcxnvgsxOVBI/GqMk9aXzyu5TsAKe1s/xlJ8JT+i4Mq3TLuZV1A9u52JzUuACr75DZoblu9U+b0krg==
- LIHWjjBy/SiN3UTZz7en+RiVyOHlOw4Av29egn9nlR8ZnTsIC0ZQ1evGVy0/4JeEk69cyWNkvRmzjKqc3xIoWw==
The target config file can be edited while the API Guard is running and is reloaded automatically. If an error occurs while reloading the config file, the last valid config will be used instead.
It is also allowed to start the API Guard with a missing target config file. Without targets or tokens, any access to the API Guard results in a 401 Unauthorized response, though.
With the example targets.yaml above, the following request would be forwarded to https://zabbix-dev.example.com/api_jsonrpc.php:
curl -X POST https://apiguard.example.com/some/path -H 'Content-Type: application/json' -H 'X-API-GUARD: Bearer mytoken' -d '{"jsonrpc":"2.0","method":"apiinfo.version","params":{},"id":1}'Any path included in the request to the API Guard will be ignored, and the request will be forwarded to the configured destination https://zabbix-dev.example.com/api_jsonrpc.php.
This example starts an API Guard using targets from the target config file targets.yaml using the default port 8080:
./api-guard start --targets targets.yaml --listen ":8080"To enable TLS, use --tls and then set the certificate path with --tls-cert-path and the key file with --tls-key-path:
./api-guard start --targets targets.yaml --tls --tls-cert-path server.crt --tls-key-path server.key --listen ":443"Instead of command line parameters, a YAML config file can be used as well. In this case, set --config to the path of the config file:
./api-guard start --config api-guard.yamlThe content of api-guard.yaml can look like this:
log-level: 6
targets: targets.yaml
tls: true
tls-cert-path: server.crt
tls-key-path: server.key
listen: ":443"If --config is not specified, ~/.api-guard.yaml is checked and loaded if found.
The command line help can be retrieved using start --help:
Usage:
api-guard start [flags]
Flags:
-h, --help help for start
--listen string The address and port that the API Guard should listen to (default ":8080")
--targets string Path to a target configuration file (default "targets.yaml")
--tls Start API Guard with TLS support
--tls-cert-path string Path to the API Guard certificate file used for TLS (default "server.crt")
--tls-key-path string Path to the API Guard certificate key file used for TLS (default "server.key")
Global Flags:
--config string config file (default is $HOME/.api-guard.yaml)
--log-level int Logging level between 0 and 6, higher values increase verbosity (default 4)
A Prometheus metrics endpoint is available at the path /metrics. Metrics are disabled on default and can be enabled in the targets.yaml config:
metrics:
enabled: true
tokens:
- mytoken
- mystatstoken
targets:
zabbixDev:
...The list of tokens can be any token used in targets or new tokens used specifically for the metrics endpoint.
To view the API Guard's metrics, the /metrics request must contain the X-API-GUARD: Bearer mytoken header.
A Zabbix template is available in the folder Zabbix that uses the metrics endpoint for monitoring. The template is compatible with Zabbix 6.x and Zabbix 7.x.
After importing the template, assign it to a host of your choice and set {$METRIC_API_URL} to the API Guard URL (with the path /metrics) and {$METRIC_API_TOKEN} to a token that is listed in the metrics token list.
Important: You must not include the Bearer prefix in the ${METRIC_API_TOKEN} macro value. The template will automatically add the Bearer prefix in the X-API-GUARD header.
The template provides a set of items that let you keep an eye on the health, usage and security of your API Guard instance. For example, you can monitor the rate of denied requests (spikes can indicate a possible brute‑force attack) and unusually large request payloads.
The binaries are available for Linux AMD64 and ARM64. The binaries can be downloaded from the Releases page.
From the directories of the api-guard repository, create the api-guard system directories and copy the files on the desired host.
sudo mkdir -p /usr/local/intellitrend/api-guard/bin/
sudo mkdir -p /usr/local/intellitrend/api-guard/etc/
sudo cp dist/intellitrend-api-guard.service /etc/systemd/system/intellitrend-api-guard.service
sudo cp dist/config.yaml /usr/local/intellitrend/api-guard/etc/config.yaml
sudo cp dist/targets.example.yaml /usr/local/intellitrend/api-guard/etc/targets.yaml
# download from releases page
bunzip api-guard-linux-amd64.bz2
sudo mv api-guard-linux-amd64 /usr/local/intellitrend/api-guard/bin/api-guardThe api-guard binary has to be executable and owned by the user root.
sudo chmod +x /usr/local/intellitrend/api-guard/bin/api-guard
sudo chown root:root /usr/local/intellitrend/api-guard/bin/api-guardRestart systemd daemon to load new service files:
sudo systemctl daemon-reloadThen enable and start the service:
sudo systemctl enable --now intellitrend-api-guardAn docker-compose.yaml configuration file is provided in the docker directory. Inside that directory you’ll find a build sub‑directory that holds the Dockerfile. To use it:
- Copy the API Guard binary into the
docker/builddirectory and name it api-guard (make sure it’s executable, e.g.chmod 0755 api-guard). - From the
dockerdirectory, start the containers withdocker-compose up -d
The docker compose file will build the image using the Dockerfile in docker/build and launch the service.
You can test the API Guard using curl. In this example, we send an apiinfo.version request on the Zabbix API through the API Guard:
curl -X POST https://apiguard.example.com -H 'Content-Type: application/json' -H 'X-API-GUARD: Bearer mytoken' -d '{"jsonrpc":"2.0","method":"apiinfo.version","params":{},"id":1}'The API Guard should then return the Zabbix frontend response:
{"jsonrpc":"2.0","result":"7.0.16","id":1}
To connect to your Zabbix frontend with Zabbix Direct in the IntelliTrend Mobile for Zabbix app, just use the API Guard's address instead of the Zabbix frontend URL and enter your API Guard token in the API guard token field.
Important: You must not include the Bearer prefix. The app will automatically add the Bearer prefix in the X-API-GUARD header.
After signing in, all requests made by the app will go to API Guard and will be forwarded to your Zabbix frontend.
If you don't have the IntelliTrend Mobile app yet, you can get it here:
When adding your Zabbix server in DataForge, use the API Guard address again instead of the Zabbix frontend address. Open Additional connection settings, set Security mode to API Guard, and paste your API Guard token into the API Guard field.
Important: You must not include the Bearer prefix. DataForge will automatically add the Bearer prefix in the X-API-GUARD header.
After your Zabbix server has been added to DataForge, your users can login as DataForge users with a valid API Guard token like this:
For more information about DataForge, please refer to the official documentation.
HTTP requests to the API Guard may return the following status codes:
| HTTP Code | Meaning |
|---|---|
| 200 OK | Request was sent successfully to the Zabbix frontend. |
| 401 Unauthorized | The bearer token is either missing or invalid. |
| 405 Method Not Allowed | Request was not sent as HTTP POST. |
| 400 Bad Request | Request was not sent with content type "application/json". |
| 502 Bad Gateway | Request could not be sent to the Zabbix frontend due to network issues. |
The status codes and body from the Zabbix frontend are forwarded as is. In case there's no reply available, the body is left empty.