Backup & Restore API

DRAFT — Internal Developer Use Only

This API reference is for internal development teams.

Overview

What it is: The Backup & Restore API provides endpoints for creating, downloading, and restoring encrypted backups of both the registry (configuration data) and the datastore (entity/identity data). Backups are encrypted ZIP files identified by KSUID.

Sources: src/registry/rest/rest.go, src/datastore/rest/rest.go

Authentication

All endpoints require JWT cookie or API token authentication. User claims (tenant, identity, email) are embedded in backup metadata.

Endpoints

Registry Backup

Method	Path	Description
POST	/internal/v1/registry/backup	Create a registry configuration backup
POST	/internal/v1/registry/restore	Restore registry from backup file
GET	/internal/v1/registry/backup/:node/:backup	Download a registry backup file

Datastore Backup

Method	Path	Description
POST	/internal/v1/datastore/backup	Create a datastore entity backup
POST	/internal/v1/datastore/restore	Restore datastore from backup file
GET	/internal/v1/datastore/backup/:node/:backup	Download a datastore backup file

---

POST /internal/v1/registry/backup

Create an encrypted backup of all registry configuration data.

Request:

POST /internal/v1/registry/backup
Content-Type: application/json
Authorization: Bearer <token>

{
  "secret": "strong-encryption-passphrase"
}

Request fields:

Field	Type	Required	Description
secret	string	Yes	Encryption passphrase for the backup ZIP. Must meet password complexity requirements.

Response (200):

{
  "id": "2GxBsGZA8gGzJDqTnVfYstMeaXd",
  "node": "node-uuid",
  "date": 1707700800000
}

Response fields:

Field	Type	Description
id	string	Backup identifier (KSUID format)
node	string	Node ID where the backup was created
date	int64	Backup creation timestamp (ms)

Backup metadata (embedded in ZIP): tenant ID, user identity, user ID, email, and name from the authenticated session.

---

POST /internal/v1/registry/restore

Restore registry configuration from an encrypted backup file. Uploaded as a multipart form.

Request:

POST /internal/v1/registry/restore
Content-Type: multipart/form-data
Authorization: Bearer <token>

Form fields:

Field	Type	Description
file	file	The backup ZIP file
secret	string	Decryption passphrase (must match the one used during backup)

Response (200):

{
  "records": 245,
  "failed": 0,
  "error": ""
}

Response fields:

Field	Type	Description
records	int64	Number of configuration records restored
failed	int64	Number of records that failed to restore
error	string	Error message (empty on success)

---

GET /internal/v1/registry/backup/:node/:backup

Download a previously created registry backup file.

Request:

GET /internal/v1/registry/backup/:node/:backup
Authorization: Bearer <token>

Path parameters:

Parameter	Description
node	Node ID where the backup was created
backup	Backup ID (KSUID)

Response (200): Binary ZIP file.

Response headers:

Header	Value
Content-Disposition	attachment; filename=hydden-tenant-{id}-{timestamp}.zip
Content-Type	application/octet-stream

---

POST /internal/v1/datastore/backup

Create an encrypted backup of all datastore entity data.

Request:

POST /internal/v1/datastore/backup
Content-Type: application/json
Authorization: Bearer <token>

{
  "secret": "strong-encryption-passphrase"
}

Response (200):

{
  "id": "2GxBsGZA8gGzJDqTnVfYstMeaXd",
  "node": "node-uuid",
  "date": 1707700800000
}

Same structure as registry backup response.

---

POST /internal/v1/datastore/restore

Restore datastore entity data from an encrypted backup file.

Request:

POST /internal/v1/datastore/restore
Content-Type: multipart/form-data
Authorization: Bearer <token>

Form fields: Same as registry restore (file + secret).

Response (200):

{
  "stores": 12,
  "records": 45230,
  "failed": 0,
  "error": ""
}

Response fields:

Field	Type	Description
stores	int64	Number of data stores restored
records	int64	Number of entity records restored
failed	int64	Number of records that failed to restore
error	string	Error message (empty on success)

---

GET /internal/v1/datastore/backup/:node/:backup

Download a previously created datastore backup file.

Request:

GET /internal/v1/datastore/backup/:node/:backup
Authorization: Bearer <token>

Path parameters: Same as registry backup download.

Response (200): Binary ZIP file.

Response headers:

Header	Value
Content-Disposition	attachment; filename=hydden-registry-{timestamp}.zip
Content-Type	application/octet-stream

---

Error Responses

Status	Description
400	Invalid request body, weak encryption secret, or corrupt backup file
403	Authentication failed or insufficient permissions
404	Backup not found (invalid node or backup ID)
500	Internal server error during backup/restore operation

Related Topics

• Registry Configuration API — Configuration CRUD operations
• Datastore API — Entity and shard management