Backup & Restore

HAP can back up and restore your authentication data on demand — the whole platform, or a single tenant — and restore it onto the same instance (rollback) or a fresh one (disaster recovery / migration). The capability is restricted to administrators: a platform operator (the root admin API key) for full or any-tenant operations, and a tenant administrator for their own tenant via the Hosted Admin console.

Everything here is reachable through the typed REST API; the Hosted console is a convenience client over the same operations.

Concepts

Scope — full (every tenant plus platform-global records) or tenant (one tenant's complete data). Full scope requires the platform operator.
Fidelity — full (includes the secret material needed for an exact restore) or redacted (secrets removed, for safe export/inspection). Only full-fidelity backups can be restored.
Artifact — a single encrypted file. It is encrypted with a key derived from a passphrase you choose, so it is portable to another instance that does not share this one's encryption key. Keep the passphrase safe — without it the backup cannot be restored.
Restore mode —
- complete replacement: make the target exactly match the backup. Records are added/overwritten first, then records absent from the backup are removed. This can delete data (up to whole tenants for a full backup), so it requires a preview + explicit confirmation.
- add/overwrite only: create/update the backup's records and leave everything else untouched (non-destructive merge).
Online & serialized — backup and restore run without taking the server down; only one runs at a time platform-wide.
Audit history is never deleted by a restore.

REST API

Authenticate with X-Admin-Key (the platform operator's bootstrap key, or a scoped admin key). Scopes: backups:read, backups:write, backups:restore.

Method & path	Purpose
`POST /v1/backups`	Create a backup (`scope`, `tenant_id?`, `fidelity`, `passphrase`).
`GET /v1/backups`	List backups in your scope.
`GET /v1/backups/{id}`	Status + metadata.
`GET /v1/backups/{id}/download`	Download the encrypted artifact.
`DELETE /v1/backups/{id}`	Delete a backup.
`POST /v1/restores`	Restore — `dry_run` for a preview, then re-submit with the returned `confirmation_token`. Source is a stored `backup_id` or an uploaded `artifact` file.
`GET /v1/restores/{id}`	Restore status, progress, and any skipped-conflict report.

Example: full disaster-recovery backup → restore to a fresh instance

# 1) Back up everything (on the source)
BID=$(curl -s -X POST $HAP/v1/backups -H "X-Admin-Key: $KEY" -H 'Content-Type: application/json' \
  -d '{"scope":"full","fidelity":"full","passphrase":"correct horse battery staple"}' | jq -r .id)
curl -s $HAP/v1/backups/$BID/download -H "X-Admin-Key: $KEY" -o hap-full.bkp

# 2) Preview the restore on the TARGET, then confirm
TOKEN=$(curl -s -X POST "$TARGET/v1/restores?dry_run=true" -H "X-Admin-Key: $TKEY" \
  -F mode=complete_replacement -F passphrase='correct horse battery staple' \
  -F artifact=@hap-full.bkp | jq -r .confirmation_token)
curl -s -X POST $TARGET/v1/restores -H "X-Admin-Key: $TKEY" \
  -F mode=complete_replacement -F passphrase='correct horse battery staple' \
  -F confirmation_token=$TOKEN -F artifact=@hap-full.bkp

Refusals (checked before any data changes)

backup_not_restorable — the artifact is redacted (export-only).
backup_corrupt — wrong passphrase, or the artifact was tampered with / truncated.
backup_incompatible_version — the backup was taken from an incompatible platform version.
operation_in_progress — another backup or restore is already running.
confirmation_required / confirmation_invalid — a complete-replacement restore needs a valid token from a dry-run preview.

Hosted Admin console (tenant administrators)

A tenant administrator opens Admin → Backups (/t/{slug}/hosted/admin/backups) to back up and restore their own tenant only. They can create full or redacted backups, download or delete them, and restore one of their backups (a complete-replacement restore shows what would be removed and asks for confirmation first).

Good to know

A restore recreates whatever the backup contained at the time it was taken, including records that were deleted afterwards. If you have honoured data-erasure ("right to be forgotten") requests since the backup, re-apply them after restoring.
Backups contain sensitive material — store the artifact and its passphrase securely.

Out of scope (v1)

Scheduled/automatic backups, incremental/point-in-time backups, cross-version restore, and restoring from a redacted backup are not supported in this version.