API and settings reference
The API
Everything except /health needs the X-Api-Key header. The checks answer on an unlicensed
installation; what a license changes is described in Licensing.
A call that also carries X-Antelao-Session is made as that account, and is held to its role:
401 when the session has ended, 403 when the role does not allow it. A call with the key alone
has full access. See Accounts.
The service's own routes are under /api/v1. Every change there answers 202 Accepted with the
job that makes it; see Every change is a job.
| Method | Route | What it does |
|---|---|---|
| GET | /health | Liveness. Anonymous |
| POST | /api/v1/check | Checks an address, a domain and a client IP against your own entries and the public lists. See Checks |
| POST | /api/v1/check/batch | Up to 100 checks in one call, answered in their order |
| GET | /api/v1/entries | Your own entries and the lists' exceptions, the deployment's first and locked |
| POST | /api/v1/entries | Queues adding an entry. Operators and administrators |
| DELETE | /api/v1/entries/{id} | Queues removing an entry. Operators and administrators |
| GET | /api/v1/sources | Every public list the license covers, with its terms, its schedule and its state |
| PUT | /api/v1/sources/{key} | Queues saving a list's on/off and schedule |
| POST | /api/v1/sources/{key}/refresh | Queues a refresh of a list now. Refused for a list the license does not cover, inside a list's least time between downloads, and with 409 while one is queued or running |
| GET | /api/v1/dashboard | The checks per day and the hits per list over the last 7, 30 or 90 days (?days=) |
| GET | /api/v1/jobs | The newest jobs first (?take=, up to 1,000) |
| GET | /api/v1/jobs/{id} | One job and how it ended |
| GET | /api/v1/security/rules | Every door's stored rules, the deployment's locked entries and the policy in force |
| PUT | /api/v1/security/rules/{application}/{surface} | Queues saving one door's rules: console/admin for the console, api/admin for the management API, api/checks for the checks |
| GET | /api/v1/security/rules/resolve | What a host name resolves to (?hostname=), for checking a rule |
| GET | /api/v1/security/log/query | One page of the firewall log, filtered, with its counts |
| GET | /api/v1/security/log/export | Every matching row of the firewall log as CSV |
| GET, PUT, DELETE | /api/v1/security/threat/settings | Threat protection's settings in force; queues saving them, or handing them back to the deployment's |
| GET, POST | /api/v1/security/threat/bans | The bans in force (?includePast=true adds the lifted and lapsed ones); queues a ban by hand |
| DELETE | /api/v1/security/threat/bans/{id} | Queues lifting a ban |
| GET | /api/v1/security/threat/failures | The newest failed attempts threat protection counted (?take=) |
A few further routes under /api/v1/security serve the console's own door and answer only the
console's key.
The routes this service shares with the other Antelao services keep their unversioned paths, and answer directly rather than with a job:
| Method | Route | What it does |
|---|---|---|
| GET, POST | /apikeys | Lists the keys that can reach this API, or issues one |
| DELETE | /apikeys/{id} | Revokes an issued key |
| POST | /apikeys/{id}/delete | Deletes a revoked or expired issued key; a live key is refused |
| GET, POST, DELETE | /license | Shows, installs or removes the license |
| POST | /license/activate | Activates a license key against the license server |
| POST, DELETE | /license/sponsor | Accepts a parent product's license as proof this installation is covered, or removes the stored sponsorship. See Sponsored by an Odoo Host Manager license |
| GET | /options | The service's settings, and where each of them came from |
| PUT, DELETE | /options/ratelimit | Sets the rate limit of the checks, or hands control back to the environment |
| GET, PUT, DELETE | /smtp | Outgoing mail settings. The password is never returned |
| POST | /smtp/test | Sends a test message with the settings in force. Saves nothing |
| GET | /backup | The service's database and the license as one archive. Refused to a read-only key |
| POST | /restore | Reads an archive back over them |
| GET, PUT | /support/settings | The support policy in force |
| GET, POST, DELETE | /support/traces | The session traces kept on this service; GET /support/traces/download?file= downloads one |
| GET | /release-notes | The release notes built into the running service, newest first |
The routes behind the console's accounts:
| Method | Route | What it does |
|---|---|---|
| POST | /account/sign-in, /account/sign-in/code | Signs an account in with its password, then its authenticator code, and answers with a session |
| POST | /account/sign-in/passkey/options, /account/sign-in/passkey | Signs an account in with a passkey |
| GET | /account | The signed-in account |
| POST | /account/sign-out | Ends this session |
| PUT | /account/profile | Changes your own display name and e-mail |
| POST | /account/password | Changes your own password |
| POST | /account/totp/setup, /account/totp/confirm, /account/totp/disable, /account/recovery-codes | The authenticator app and its recovery codes |
| GET, POST, DELETE | /account/passkeys | Your passkeys |
| GET, DELETE | /account/sessions | Your sessions; POST /account/sessions/end-others ends all but this one |
| GET, POST, PUT, DELETE | /users | The accounts, with /users/{id}/password, /totp/reset and /sessions/end. Reading needs an administrator or read-only administrator, changing needs an administrator |
| GET | /audit | The audit log, newest first, with a search. Administrators and read-only administrators |
| GET, PUT | /ui-memory | Your console preferences |
Settings
The API container:
| Variable | Default | What it is |
|---|---|---|
Api__Keys__<name> | - | An accepted API key. At least one is required, and it cannot be revoked through the API |
Api__ConsoleKeyName | ui or console | The name of the configured key the console uses. Only a call with that key may name the signed-in person's address for the audit log and the session list |
Api__ActorKeyNames__<n> | - | Configured keys that act for people: a call with one may name the person in X-Antelao-Actor. See Keys that act for people |
Api__TrustedProxies__<n> | - | A reverse proxy in front of the API, as an address (172.18.0.1) or a network (172.18.0.0/16). Its forwarded address and scheme are believed, and nobody else's, so the rate limit, threat protection and the audit log see the caller behind it. See A proxy that is not trusted |
Blocklist__DatabasePath | /data/blocklist.db | The service's database: entries, lists and their downloaded copies, jobs, settings, issued keys as digests, accounts, the firewall's rules and log, threat protection's state and the audit log, mode 600 |
Blocklist__Entries__<n> | - | The deployment's own entries: full addresses, and @domain for a domain with its subdomains; several in one value separated by commas or semicolons. Shown locked |
Blocklist__ScheduledRefresh | true | false stops every scheduled refresh of the public lists; they are then refreshed by hand only |
Blocklist__TracesDir | /data/traces | Where session traces are kept. Not part of a backup |
BLOCKLIST_SEED_ADMIN_PASS | generated | The built-in administrator's password, applied when the account is made and whenever the value changes |
BLOCKLIST_SEED_ADMIN_TOTP | - | The built-in administrator's authenticator secret in base32, at least 26 characters; makes two-factor required for it. Applied when the account is made, whenever the value changes and when the account no longer has it, as after a restore. An invalid value stops the API from starting |
RateLimit__Enabled | false | Whether the checks are rate limited at all |
RateLimit__PermitLimit | 600 | Requests one API key may make inside the window |
RateLimit__WindowSeconds | 60 | The window's length |
RateLimit__QueueLimit | 0 | Requests over the limit that wait rather than being refused |
Smtp__Enabled | false | Whether outgoing mail is sent at all |
Smtp__Host / Smtp__Port | - / 587 | The mail server |
Smtp__Security | StartTls | None, StartTls or SslOnConnect |
Smtp__UserName / Smtp__Password | - | Credentials, or neither to send without authenticating |
Smtp__FromAddress / Smtp__FromName | - / Antelao Blocklist | Who the mail comes from |
Smtp__NotifyTo | - | Who it goes to, separated by commas, semicolons or new lines |
Smtp__TimeoutSeconds | 30 | How long one send may take |
License__Directory | /data/license | License files and check-in state |
AccessControl__Surfaces__admin__... | - | The management API's locked firewall entries: AllowedIps__<n>, AllowedHostnames__<n>, AllowedCountries__<n>, AllowedContinents__<n>. See Firewall |
AccessControl__Surfaces__checks__... | - | The same for the checks |
AccessControl__GeoDatabasePath | - | A GeoLite2 country database file, for the firewall's country and continent rules and the log's countries. Unset, location rules are switched off |
threatProtection__... | see Threat protection | Threat protection's thresholds, whitelist and mail |
The mail settings are named as this service and GeoIP read them. Antelao Fail2Ban names three of them
differently and has no Smtp__Enabled, so do not copy a mail block from that product's compose file.
The console container:
| Variable | Default | What it is |
|---|---|---|
BlocklistApi__BaseUrl / BlocklistApi__ApiKey | - | The API's address and the key the console presents |
Ui__SessionHours | 12 | How long a sign-in lasts at most. A session unused for two hours ends sooner |
Ui__TrustedProxies__<n> | - | The reverse proxy in front of the console, as an address (172.18.0.1) or a network (172.18.0.0/16). Its forwarded address and scheme are believed, and nobody else's. See A proxy that is not trusted |
Ui__AllowPlainHttp | false | true lets the console keep a sign-in over plain HTTP on a name other than localhost. The sign-in cookie can then be read by anyone on the network between the browser and the console, and the console warns about it at every start. Only for a trusted network with no HTTPS in front of the console |
Turnstile__SiteKey | - | The site key of the optional Cloudflare Turnstile check on the sign-in page. The check is on only when this and Turnstile__SecretKey are both set. See Cloudflare Turnstile |
Turnstile__SecretKey | - | Its secret key, used only to verify each answer with Cloudflare. The console then needs outbound HTTPS to challenges.cloudflare.com, and refuses a sign-in when Cloudflare cannot be reached |
Turnstile__Bypass | false | The emergency bypass: true switches the Turnstile check off although both keys are set. The start argument --Turnstile:Bypass=true does the same. Warned about at every start and noted on every sign-in in the audit log |
Turnstile__Hostnames__<n> | - | The hostnames a Turnstile answer may come from, such as the console's public name. Unset skips that check |
DataProtection__KeysPath | - | Where the console keeps the keys its sessions are protected with. Put it on a volume, so a restart does not drop every open page |
The console's own door in the firewall is set on the console container, with
AccessControl__Surfaces__admin__AllowedIps__<n> and its siblings and, for location rules,
AccessControl__GeoDatabasePath. See Firewall.