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 short‑lived JWT token used for authentication:

$ seedpass api start
API token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...

Keep this token secret and avoid logging it. Tokens expire after a few minutes and every request must include one in the Authorization header using the Bearer scheme.

Endpoints

Secure Deployment

Always run the API behind HTTPS. Use a reverse proxy such as Nginx or Caddy to terminate TLS and forward requests to SeedPass. Example Nginx configuration:

server {
    listen 443 ssl;
    ssl_certificate     /etc/letsencrypt/live/example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

For local testing, Uvicorn can serve TLS directly:

uvicorn seedpass.api:app --ssl-certfile=cert.pem --ssl-keyfile=key.pem

Example Requests

Send requests with the token in the header:

curl -H "Authorization: Bearer <token>" \
     "https://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 https://127.0.0.1:8000/api/v1/vault/export \
     -H "Authorization: Bearer <token>" \
     -H "X-SeedPass-Password: <master-password>" \
     -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 file=@backup.json

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 "X-SeedPass-Password: <master password>" \
     -H "Content-Type: application/json" \
     -d '{"path": "seed_backup.enc", "confirm": true}'

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.