SeedPass REST API Reference

This guide covers how to start the SeedPass API, authenticate requests, and interact with the available endpoints.

Note: All UI layers, including the CLI, BeeWare GUI, and future adapters, consume this REST API through service classes in seedpass.core. See docs/gui_adapter.md for more details on the GUI integration.

Starting the API

Run seedpass api start from your terminal. The command prints a one‑time token used for authentication:

$ seedpass api start
API token: abcdef1234567890

Keep this token secret. Every request must include it in the Authorization header using the Bearer scheme.

Endpoints

Security Warning: Accessing /api/v1/parent-seed exposes your master seed in plain text. Use it only from a trusted environment.

Example Requests

Send requests with the token in the header:

curl -H "Authorization: Bearer <token>" \
     "http://127.0.0.1:8000/api/v1/entry?query=email"

Creating an Entry

POST /api/v1/entry accepts a JSON body with at least a label field. Set type (or kind) to choose the entry variant (password, totp, ssh, pgp, nostr, seed, key_value, or managed_account). Additional fields vary by type:

Example creating a TOTP entry:

curl -X POST http://127.0.0.1:8000/api/v1/entry \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{"type": "totp", "label": "Email", "secret": "JBSW..."}'

Updating an Entry

Use PUT /api/v1/entry/{id} to change fields such as label, username, url, notes, period, digits or value depending on the entry type.

curl -X PUT http://127.0.0.1:8000/api/v1/entry/1 \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{"username": "alice"}'

Updating Configuration

Send a JSON body containing a value field to PUT /api/v1/config/{key}:

curl -X PUT http://127.0.0.1:8000/api/v1/config/inactivity_timeout \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{"value": 300}'

To raise the PBKDF2 work factor or change how often backups are written:

curl -X PUT http://127.0.0.1:8000/api/v1/config/kdf_iterations \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{"value": 200000}'

curl -X PUT http://127.0.0.1:8000/api/v1/config/backup_interval \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{"value": 3600}'

Using fewer iterations or a long interval reduces security, so adjust these values carefully.

Toggling Secret Mode

Send both enabled and delay values to /api/v1/secret-mode:

curl -X POST http://127.0.0.1:8000/api/v1/secret-mode \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{"enabled": true, "delay": 20}'

Switching Fingerprints

Change the active seed profile via POST /api/v1/fingerprint/select:

curl -X POST http://127.0.0.1:8000/api/v1/fingerprint/select \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
    -d '{"fingerprint": "abc123"}'

Exporting the Vault

Download an encrypted vault backup via POST /api/v1/vault/export:

curl -X POST http://127.0.0.1:8000/api/v1/vault/export \
     -H "Authorization: Bearer <token>" \
     -o backup.json

Importing a Vault

Restore a backup with POST /api/v1/vault/import. Use -F to upload a file:

curl -X POST http://127.0.0.1:8000/api/v1/vault/import \
     -H "Authorization: Bearer <token>" \
     -F [email protected]

Locking the Vault

Clear sensitive data from memory using /api/v1/vault/lock:

curl -X POST http://127.0.0.1:8000/api/v1/vault/lock \
     -H "Authorization: Bearer <token>"

Backing Up the Parent Seed

Trigger an encrypted seed backup with /api/v1/vault/backup-parent-seed:

curl -X POST http://127.0.0.1:8000/api/v1/vault/backup-parent-seed \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{"path": "seed_backup.enc"}'

Retrieving Vault Statistics

Get profile stats such as entry counts with GET /api/v1/stats:

curl -H "Authorization: Bearer <token>" \
    http://127.0.0.1:8000/api/v1/stats

Checking Notifications

Get queued messages with GET /api/v1/notifications:

curl -H "Authorization: Bearer <token>" \
     http://127.0.0.1:8000/api/v1/notifications

The TUI displays these alerts in a persistent notification box for 10 seconds, but the endpoint returns all queued messages even if they have already disappeared from the screen.

Changing the Master Password

Update the vault password via POST /api/v1/change-password:

curl -X POST http://127.0.0.1:8000/api/v1/change-password \
     -H "Authorization: Bearer <token>"

Verifying the Script Checksum

Check that the running script matches the stored checksum:

curl -X POST http://127.0.0.1:8000/api/v1/checksum/verify \
     -H "Authorization: Bearer <token>"

Updating the Script Checksum

Regenerate the stored checksum using /api/v1/checksum/update:

curl -X POST http://127.0.0.1:8000/api/v1/checksum/update \
     -H "Authorization: Bearer <token>"

Managing Relays

List, add, or remove Nostr relays:

# list
curl -H "Authorization: Bearer <token>" http://127.0.0.1:8000/api/v1/relays

# add
curl -X POST http://127.0.0.1:8000/api/v1/relays \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{"url": "wss://relay.example.com"}'

# remove first relay
curl -X DELETE http://127.0.0.1:8000/api/v1/relays/1 \
     -H "Authorization: Bearer <token>"

# reset to defaults
curl -X POST http://127.0.0.1:8000/api/v1/relays/reset \
     -H "Authorization: Bearer <token>"

Enabling CORS

Cross‑origin requests are disabled by default. Set SEEDPASS_CORS_ORIGINS to a comma‑separated list of allowed origins before starting the API:

SEEDPASS_CORS_ORIGINS=http://localhost:3000 seedpass api start

Browsers can then call the API from the specified origins, for example using JavaScript:

fetch('http://127.0.0.1:8000/api/v1/entry?query=email', {
  headers: { Authorization: 'Bearer <token>' }
});

Without CORS enabled, only same‑origin or command‑line tools like curl can access the API.