API Access

Everything you do in the console — reading/updating configuration, managing rules, blocking IPs, purging the cache, usage reports — can also be done programmatically through the HEIMWALL REST API. It is designed for CI/CD pipelines, monitoring systems and your own dashboards.

The detailed API reference lives in the console

The full API documentation — the endpoint list, request/response schemas and examples — is accessible only after signing in to the console, as a security measure. Where to find it is explained below.

Accessing the detailed API documentation

1. Sign in to the console at https://cloud.heimwall.net/.

2. Open Console → WAF → [domain] → API Keys.

3. Click the “Open API Documentation” link on the page. The API Documentation viewer opens inside the panel: all endpoints, parameters, request/response schemas and error codes are documented there. You can also download the machine-readable spec via the “Raw spec (OpenAPI)” link.

For reseller accounts, the same documentation opens from the API Documentation link under Reseller Panel → Integrations.

Creating an API key

1. Create a new key on Console → WAF → [domain] → API Keys.

2. Give the key a name and tick the scopes it needs — each key can only perform the operations you select.

3. Optionally add an IP restriction (the key only works from the IPs/CIDRs you specify) and set an expiry date.

4. The generated key is shown only once — copy it immediately and store it in your password manager or secrets vault. Keys are stored server-side as irreversible hashes; if you lose one, revoke it and create a new one.

A domain can have at most 20 active keys. You can revoke keys and update their name and scopes from the same page.

Scopes

Following the principle of least privilege, each key should get only the scopes it needs:

Scope	What it allows
config:read	Reading configuration, rules and protection settings
config:write	Configuration and rule changes, IP blocking
usage:read	Reading traffic and usage data
cache:purge	Purging the cache

Example: a CI/CD key

For a key that only purges the cache after deploys, grant just the cache:purge scope and set the IP restriction to your deploy server’s address. Even if the key leaks, the only thing it can do is purge the cache.

Security and usage notes

• Authentication uses a Bearer token; you send your key in the Authorization header. The exact format is shown in the in-panel documentation.
• Rate limiting applies; track your remaining quota via the X-RateLimit-Limit and X-RateLimit-Remaining response headers. Exceeding the limit returns 429 with Retry-After.
• Audit trail: every change made through the API is recorded in the Audit Log under the key’s name — who changed what, and when, is always traceable.
• Rotate keys periodically: create a new one, migrate your systems, revoke the old one.
• Never put a key in client-side code, a repository or logs.

Related pages

WebhooksPush events to your systems instantly, without polling the API.

Purging the CacheIncludes the API-based cache purge scenario.

Audit LogThe trail of changes made with API keys.

Zero-Downtime DeploymentSeparate deploy hooks for the CI/CD deploy flow.