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.

Read-only keys​

A read-only key may only issue GET requests: it is refused a POST, PUT or DELETE before a route is chosen.

It can read lookups and change nothing, not even issue itself a better key.

Backup and restore​

GET /backup is one archive holding everything this service keeps that cannot be downloaded again: the service's database - the MaxMind credential, the keys issued here, the rate limit, the mail settings, the accounts 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.

Five things to know:

  • The GeoLite2 databases are not in it. They are eighty megabytes MaxMind hands back for free under the credential the archive already carries, and a restored service re-downloads them within a minute of starting.
  • It is not encrypted. It carries the MaxMind license key, the mail password and the license file in the clear. Keep it where you keep your other credentials. A passphrase this service invented would be one more thing to lose. 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. An app's secret would be a working second factor in whoever holds the file, so 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 rather than a third state that is neither - including its accounts, 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 is applied again after a restore, from GEOIP_SEED_ADMIN_PASS, so restoring an old archive cannot lock you out. An archive taken by a release before accounts still restores; it brings the settings and keys, and the accounts stay as they are.
  • A set authenticator seed is applied again after a restore as well, from GEOIP_SEED_ADMIN_TOTP, so the built-in administrator keeps its required second factor.

Everything but the license takes effect immediately. The license is read at start-up, so a restore that carried one tells you to restart the container.

Last updated on