API reference
How the PulsVault REST API is organized, how API authentication works, and how to request the endpoint reference.
PulsVault's backend exposes a REST API — the same one the official clients use. This page explains how the API is organized and how authentication works; it is not an endpoint-by-endpoint listing.
Getting the endpoint reference#
The detailed endpoint reference is not published on this site. Team, business, and enterprise customers can request it — along with integration guidance — through a support ticket or their sales or account contact.
Requests are handled case by case, so tell us what you are building: which areas of the API you need (see Main API areas below) and whether the integration touches encrypted vault data.
Authentication model#
The API mirrors the product's two-gate model:
- Gate 1 — account session. Sign in via the auth endpoints. Browser clients receive an HTTP-only session cookie; mobile and non-browser clients use the token returned by the mobile login endpoint and send it on subsequent requests. Every other call has to carry that session, so sign in first.
- Gate 2 — vault session. Endpoints that touch encrypted vault data additionally require an unlocked vault session (established with an Access Key, Recovery Key, or trusted device).
Secret fields cross the API only as ciphertext, and keys only in wrapped form. Encryption and decryption happen in the client — no endpoint accepts or returns a plaintext secret. Item names and non-secret fields are ordinary JSON (what is and isn't encrypted). See How encryption works.
Main API areas#
Grouping below follows the backend's controller packages:
| Area | What it covers |
|---|---|
| Authentication | Sign-in/sign-up, auth challenges, admin auth |
| Users & account | Profile, preferences, settings, account setup and deletion |
| Vaults & items | Vaults, items, notes, folders, attachments, item schemas, password health |
| Sharing | Shared access, secure shared links, item sharing info |
| Security | 2FA/TOTP, trusted devices, vault sessions, device management, travel mode, breach monitoring, IP blocking, key recovery |
| Audit | Audit log queries and exports |
| Organizations & teams | Organization settings, team and family management, roles and permissions |
| Billing & subscription | Stripe checkout and webhooks, subscriptions, entitlements, usage |
| Search | Global search across unlocked data |
| Files & integrations | File storage, Google Drive / OneDrive connectors, integrations |
| Notifications | In-app notification delivery |
| Public | Unauthenticated endpoints: pricing packs, email OTP, geo lookup, sales inquiries |
Notes for integrators#
- There is no separate public API-key program today; the API is the same one the official clients use, and abuse protection (IP blocking) applies to it.
- Building against vault-data endpoints means implementing client-side crypto — review the encryption architecture first.
- A command-line client is on the roadmap.