seedPass/docs/docs/content/01-getting-started/02-api_reference.md

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

• GET /api/v1/entry?query=<text> – Search entries matching a query.
• GET /api/v1/entry/{id} – Retrieve a single entry by its index. Requires an X-SeedPass-Password header.
• POST /api/v1/entry – Create a new entry of any supported type.
• PUT /api/v1/entry/{id} – Modify an existing entry.
• PUT /api/v1/config/{key} – Update a configuration value.
• POST /api/v1/secret-mode – Enable or disable Secret Mode and set the clipboard delay.
• POST /api/v1/entry/{id}/archive – Archive an entry.
• POST /api/v1/entry/{id}/unarchive – Unarchive an entry.
• GET /api/v1/config/{key} – Return the value for a configuration key.
• GET /api/v1/fingerprint – List available seed fingerprints.
• POST /api/v1/fingerprint – Add a new seed fingerprint.
• DELETE /api/v1/fingerprint/{fp} – Remove a fingerprint.
• POST /api/v1/fingerprint/select – Switch the active fingerprint.
• GET /api/v1/totp/export – Export all TOTP entries as JSON. Requires an X-SeedPass-Password header.
• GET /api/v1/totp – Return current TOTP codes and remaining time. Requires an X-SeedPass-Password header.
• GET /api/v1/stats – Return statistics about the active seed profile.
• GET /api/v1/notifications – Retrieve and clear queued notifications. Messages appear in the persistent notification box but remain queued until fetched.
• GET /api/v1/nostr/pubkey – Fetch the Nostr public key for the active seed.
• POST /api/v1/checksum/verify – Verify the checksum of the running script.
• POST /api/v1/checksum/update – Update the stored script checksum.
• POST /api/v1/change-password – Change the master password for the active profile.
• POST /api/v1/vault/import – Import a vault backup from a file or path.
• POST /api/v1/vault/export – Export the vault and download the encrypted file. Requires an additional X-SeedPass-Password header.
• POST /api/v1/vault/backup-parent-seed – Save an encrypted backup of the parent seed. Requires a confirm flag in the request body and an X-SeedPass-Password header.
• POST /api/v1/vault/lock – Lock the vault and clear sensitive data from memory.
• GET /api/v1/relays – List configured Nostr relays.
• POST /api/v1/relays – Add a relay URL.
• DELETE /api/v1/relays/{idx} – Remove the relay at the given index (1‑based).
• POST /api/v1/relays/reset – Reset the relay list to defaults.
• POST /api/v1/shutdown – Stop the server gracefully.

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:

• password – length, optional username, url and notes
• totp – secret or index, optional period, digits, notes, archived
• ssh/nostr/seed/managed_account – index, optional notes, archived
• pgp – index, key_type, user_id, optional notes, archived
• key_value – value, optional notes

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.