Skip to main content

API keys and backup

Two kinds of key​

Configured keys come from the container's environment (Api__Keys__<name>). At least one is required, they are read once at start-up, and they cannot be revoked or deleted through the API, which makes them the way back in after revoking the wrong thing.

They are listed by GET /apikeys and marked as coming from the environment, beside the issued ones, so the list shows every key that can reach the service.

Issued keys are minted through the console or POST /apikeys with a description, an optional expiry and an optional read-only flag. They are stored as SHA-256 digests plus an eight-character prefix, so the file on the volume is a list of descriptions rather than a set of working credentials.

On the API keys page, a live issued key has a Revoke button (DELETE /apikeys/{id}). A revoked key is refused from the next request on and stays in the list, marked revoked. A revoked or expired key has a Delete button instead (POST /apikeys/{id}/delete), which removes it from the list for good. A live key cannot be deleted: revoke it first. Both are confirmed in the row, and the Audit log names the key by its description and prefix, so an entry still reads after the key is gone.

An issued key is returned exactly once

From the call that issued it. Nothing readable is stored, so it cannot be read back: lose it and you revoke it, mint another, and delete the revoked one.

A wrong key counts as a failed attempt for threat protection: an address that keeps presenting wrong keys is banned from the console and the management API, never from the checks.

Read-only keys​

A read-only key may issue GET requests and ask checks, and nothing else: it is refused every other POST, PUT or DELETE with 403 This API key is read-only, so it may only issue GET requests and checks.

That makes it the key to give a form: it can check addresses and read the entries, the lists and the jobs, and it cannot add an entry, change a list, or issue itself a better key. It is also refused a backup.

Keys that act for people​

A program that makes changes on behalf of the people using it - an administration console of your own, for example - can have its changes recorded under those people's names rather than under the key's. Name its configured key in the API container's environment, Api__ActorKeyNames__0=<name>; a call with that key may then name the person in the X-Antelao-Actor header, and the job and the audit log record the change as <person> (API key <name>).

Such a key may also date an entry it adds, with createdUtc in the entry, so an entry moved here from another list keeps the date it was first added. A date in the future is refused, and so is a date on a call that does not name its person through such a key.

Backup and restore​

GET /backup is one archive holding everything this service keeps that cannot be downloaded again: the service's database - your own entries and exceptions, the lists' settings and the copies in force, the jobs, the API keys issued here, the rate limit, the mail settings, the firewall rules and threat protection's bans and settings, the accounts with their preferences and the audit log - and the license. The console has it on the Options page as a download button and a file picker, for administrators only.

  • It is not encrypted. It carries the mail password and the license file in the clear, and the accounts' password digests. Keep it where you keep your other credentials. A read-only key is refused it - the one GET in the service with a gate of its own - and every download is in the audit log, marked when it was taken with a key rather than by a signed-in person.
  • Authenticator apps are left out. After a restore, an account that used one signs in with its password and sets the app up again on My account > Security. Passwords and passkeys come back.
  • Restoring is a replacement, not a merge. The database is replaced by the archive's, so afterwards the service is in the state the archive describes - its entries, lists and accounts included, and everybody signs in again. The license directory is the exception: archived files are written over it and nothing there is deleted, because it also holds check-in state the running service owns.
  • The built-in administrator's password and a set authenticator seed are applied again after a restore, from BLOCKLIST_SEED_ADMIN_PASS and BLOCKLIST_SEED_ADMIN_TOTP, so restoring an old archive cannot lock you out.
  • Only this product's archives restore. An archive from GeoIP or Fail2Ban, or from a newer release of this service, is refused before anything is written. An archive is at most 256 MB.

Everything but the license takes effect immediately, the firewall's rules and the bans included. The license is read at start-up, so a restore that carried one tells you to restart the container.

Last updated on