Overview
The API is described in OpenAPI 3.1. Every client encrypts on the device, so the API only ever sees ciphertext, key material wrapped by the client and the metadata listed on the security page.
Version: 0.2.0 · OpenAPI 3.1
Conventions and errors
HTTP API of the Passbox server. All vault data is encrypted on the client; the server only stores and relays ciphertext. Binary values are unpadded Base64url strings. Timestamps are Unix milliseconds.
Errors have the shape { "error": "<code>", "message": "...", "details"?: {...} }
with the codes bad_request, unauthorized, invalid_credentials,
not_found, conflict, rate_limited and internal, and with status 403
forbidden (not an instance admin), account_disabled,
registration_closed, domain_not_allowed and invitation_invalid.
Two-factor errors: reauthentication_required (403),
invalid_two_factor_code and two_factor_expired (401).
Recovery errors: recovery_needs_security_key (401),
emergency_access_waiting and device_link_expired (403). Account
recovery, emergency access and device codes are described in
docs/architecture/recovery.md.
Single sign-on errors (403) start with sso_, for example
sso_required, sso_proof_invalid, sso_expired or
sso_device_not_trusted; SSO, trusted devices and SCIM are described in
docs/architecture/sso.md (tags sso and scim).
Two-factor authentication: when an account has a second factor (TOTP
authenticator app or WebAuthn security key), login/finish answers with
a TwoFactorChallenge instead of a session, unless the device token sent
to login/start belongs to a device remembered within the last 30 days.
login/two-factor completes the login. The challenge only appears after
the password was verified, so unknown accounts stay indistinguishable.
Endpoints
Every endpoint of the current version, grouped by area. Request and response schemas are in the OpenAPI file.
health
| Method | Path | Summary |
|---|---|---|
| GET | /health | Liveness check |
meta
| Method | Path | Summary |
|---|---|---|
| GET | /api/v1/meta | Public server information |
auth
| Method | Path | Summary |
|---|---|---|
| POST | /api/v1/auth/prelogin | Key derivation parameters for an email |
| POST | /api/v1/auth/register/start | Start an OPAQUE registration |
| POST | /api/v1/auth/register/finish | Finish the registration and create the account with its first vault |
| POST | /api/v1/auth/login/start | Start an OPAQUE login |
| POST | /api/v1/auth/login/finish | Finish the login and receive a session token |
| POST | /api/v1/auth/login/two-factor | Complete a login with its second factor |
| POST | /api/v1/auth/logout | End the current session |
account
| Method | Path | Summary |
|---|---|---|
| GET | /api/v1/account | The signed-in account |
| GET | /api/v1/account/preferences | Mail language and notification settings |
| PUT | /api/v1/account/preferences | Change preferences (omitted fields stay) |
| GET | /api/v1/account/two-factor | Two-factor authentication status |
| POST | /api/v1/account/two-factor/totp/start | Create a TOTP secret for an authenticator app |
| POST | /api/v1/account/two-factor/totp/confirm | Turn the pending TOTP on with a first code |
| DELETE | /api/v1/account/two-factor/totp | Remove the authenticator app |
| POST | /api/v1/account/two-factor/webauthn/register/start | Start registering a security key or passkey |
| POST | /api/v1/account/two-factor/webauthn/register/finish | Store a verified security key |
| DELETE | /api/v1/account/two-factor/webauthn/{id} | Remove a security key |
| POST | /api/v1/account/two-factor/recovery-codes | Replace the recovery codes |
| POST | /api/v1/account/two-factor/challenge | Start checking a second factor while signed in |
| POST | /api/v1/account/two-factor/disable | Turn two-factor authentication off |
| GET | /api/v1/account/keys | The account's own key pairs |
| PUT | /api/v1/account/keys | Publish the account's key pairs |
| GET | /api/v1/account/recovery | Recovery status of the account (recovery code, organization escrows) |
| POST | /api/v1/account/recovery-code/start | Start registering the recovery code's OPAQUE record (login in the last 10 minutes) |
| POST | /api/v1/account/recovery-code | Store the recovery code record and the account key wrapped with it (replaces an older code) |
| DELETE | /api/v1/account/recovery-code | Remove the recovery code (login in the last 10 minutes) |
| GET | /api/v1/account/trusted-devices | Trusted devices and pending approval requests |
| POST | /api/v1/account/trusted-devices | Trust this device (login in the last 10 minutes) |
| DELETE | /api/v1/account/trusted-devices/{id} | Remove a trusted device |
| POST | /api/v1/account/trusted-devices/requests/{id}/approve | Approve a new device after comparing its code (login in the last 10 minutes) |
| POST | /api/v1/account/trusted-devices/requests/{id}/deny | Decline a new device |
admin
| Method | Path | Summary |
|---|---|---|
| GET | /api/v1/admin/settings | Instance settings and mail status |
| PUT | /api/v1/admin/settings | Change the instance settings |
| GET | /api/v1/admin/users | Accounts on the server |
| POST | /api/v1/admin/users/{id}/disable | Disable an account |
| POST | /api/v1/admin/users/{id}/enable | Enable a disabled account |
| POST | /api/v1/admin/mail/test | Queue a test mail |
| GET | /api/v1/admin/invites | Invitations, newest first |
| POST | /api/v1/admin/invites | Invite an email to create an account |
| DELETE | /api/v1/admin/invites/{id} | Withdraw an unused invitation |
| GET | /api/v1/admin/events | Admin audit log, newest first |
sync
| Method | Path | Summary |
|---|---|---|
| GET | /api/v1/sync | Changes since a cursor |
vaults
| Method | Path | Summary |
|---|---|---|
| POST | /api/v1/vaults | Create a vault |
| PUT | /api/v1/vaults/{id} | Update vault metadata |
| GET | /api/v1/vaults/{id}/access-request | Whether this account can open a vault, and its own request |
| POST | /api/v1/vaults/{id}/access-requests | Ask the vault's managers for access |
| GET | /api/v1/vaults/{id}/members | Members and manifest chain of a shared vault (members) |
| POST | /api/v1/vaults/{id}/members | Share with an account or group, or change a role (managers) |
| POST | /api/v1/vaults/{id}/rotate | Rotate the vault key, removing members (managers) |
| PUT | /api/v1/vaults/{id}/keys/{epoch}/wrapped | Store the caller's own wrapped copy of a vault key |
| POST | /api/v1/vaults/{id}/items/batch | Write up to 100 items of a vault (re-encryption after rotation) |
items
| Method | Path | Summary |
|---|---|---|
| PUT | /api/v1/items/{id} | Create (revision 1) or update an item |
| DELETE | /api/v1/items/{id} | Delete an item (keeps a tombstone) |
| GET | /api/v1/items/{id}/versions | Earlier versions of an item |
| POST | /api/v1/items/move | Move items into another vault |
attachments
| Method | Path | Summary |
|---|---|---|
| PUT | /api/v1/attachments/{id} | Upload an encrypted attachment blob |
| GET | /api/v1/attachments/{id} | Download an encrypted attachment blob |
| DELETE | /api/v1/attachments/{id} | Delete an attachment |
| GET | /api/v1/attachments/usage | Attachment limits and storage used |
share-links
| Method | Path | Summary |
|---|---|---|
| GET | /api/v1/share-links | The account's share links that have not expired |
| POST | /api/v1/share-links | Create a share link |
| DELETE | /api/v1/share-links/{id} | End a share link |
public
| Method | Path | Summary |
|---|---|---|
| GET | /api/v1/public/share-links/{id} | What the viewer needs before opening (no session) |
| POST | /api/v1/public/share-links/{id}/open | The encrypted snapshot, for the access token (no session; counts a view) |
access-requests
| Method | Path | Summary |
|---|---|---|
| GET | /api/v1/access-requests | Pending requests for vaults this account manages, and its own |
| DELETE | /api/v1/access-requests/{id} | Withdraw an own pending request |
| POST | /api/v1/access-requests/{id}/approve | Mark a request approved (after sharing the vault with the requester) |
| POST | /api/v1/access-requests/{id}/deny | Decline a request |
icons
| Method | Path | Summary |
|---|---|---|
| GET | /api/v1/icons/{domain} | A website's icon, fetched by the server |
breach
| Method | Path | Summary |
|---|---|---|
| GET | /api/v1/breach/range/{prefix} | Pwned Passwords range through the server (k-anonymity) |
| GET | /api/v1/breach/emails | Email breach monitoring of the account |
| POST | /api/v1/breach/emails | Monitor an email address (sends a confirmation code) |
| DELETE | /api/v1/breach/emails/{id} | Stop monitoring an address |
| POST | /api/v1/breach/emails/{id}/verify | Confirm an address with the mailed code |
| POST | /api/v1/breach/emails/{id}/check | Check a confirmed address now |
breaches
| Method | Path | Summary |
|---|---|---|
| GET | /api/v1/breaches/catalog | The breach catalogue (breached websites) |
| GET | /api/v1/breaches/catalog/version | Version of the breach catalogue |
keys
| Method | Path | Summary |
|---|---|---|
| GET | /api/v1/keys/head | Signed head of the key log |
| GET | /api/v1/keys/log | Entries of the key log |
| GET | /api/v1/keys/{accountId} | Look up an account's current key with a proof |
orgs
| Method | Path | Summary |
|---|---|---|
| GET | /api/v1/orgs | The account's organizations |
| POST | /api/v1/orgs | Create an organization |
| GET | /api/v1/orgs/{orgId} | An organization with its members |
| PUT | /api/v1/orgs/{orgId} | Update encrypted metadata (admins) |
| DELETE | /api/v1/orgs/{orgId} | Delete the organization and its vaults (owner) |
| POST | /api/v1/orgs/{orgId}/rotate-key | Rotate the organization key (admins) |
| GET | /api/v1/orgs/{orgId}/invitations | Pending invitations (admins) |
| POST | /api/v1/orgs/{orgId}/invitations | Invite by email (admins; admins only by the owner) |
| DELETE | /api/v1/orgs/{orgId}/invitations/{invitationId} | Revoke a pending invitation (admins) |
| PUT | /api/v1/orgs/{orgId}/members/{accountId} | Change a member's role or re-attest (admins; admin rights by the owner) |
| DELETE | /api/v1/orgs/{orgId}/members/{accountId} | Remove a member (admins) or leave |
| POST | /api/v1/orgs/{orgId}/members/{accountId}/confirm | Confirm an accepted member (admins) |
| POST | /api/v1/orgs/{orgId}/members/{accountId}/suspend | Suspend a member (admins; not cryptographic) |
| POST | /api/v1/orgs/{orgId}/members/{accountId}/reactivate | Reactivate a suspended member (admins) |
| GET | /api/v1/orgs/{orgId}/groups | Groups of an organization (confirmed members) |
| POST | /api/v1/orgs/{orgId}/groups | Create a group (admins; the creator is a member) |
| PUT | /api/v1/orgs/{orgId}/groups/{groupId} | Rename a group (admins) |
| DELETE | /api/v1/orgs/{orgId}/groups/{groupId} | Delete a group (admins) |
| POST | /api/v1/orgs/{orgId}/groups/{groupId}/members | Add a group member (one sealing of the group key) |
| POST | /api/v1/orgs/{orgId}/groups/{groupId}/rotate | Rotate a group's key, removing members (admins) |
| POST | /api/v1/orgs/{orgId}/vaults | Create a shared vault (owners and admins) |
| DELETE | /api/v1/orgs/{orgId}/recovery | Turn organization recovery off for everyone |
| GET | /api/v1/orgs/{orgId}/recovery | Organization recovery key, grants and the caller's escrow |
| POST | /api/v1/orgs/{orgId}/recovery/keys | Create the organization recovery key (owners and admins) |
| POST | /api/v1/orgs/{orgId}/recovery/grants | Seal the recovery key to another admin |
| PUT | /api/v1/orgs/{orgId}/recovery/escrow | Opt in to organization recovery (signed escrow of the account key) |
| DELETE | /api/v1/orgs/{orgId}/recovery/escrow | Withdraw from organization recovery |
| GET | /api/v1/orgs/{orgId}/recovery/requests | Pending recovery requests (recovery admins) |
| POST | /api/v1/orgs/{orgId}/recovery/requests/{requestId}/approve | Approve a recovery request (after an out-of-band identity check) |
| POST | /api/v1/orgs/{orgId}/recovery/requests/{requestId}/deny | Deny a recovery request |
| GET | /api/v1/orgs/{orgId}/sso | The organization's OIDC configuration, or null (owners and admins) |
| PUT | /api/v1/orgs/{orgId}/sso | Create or replace the configuration (team organizations) |
| DELETE | /api/v1/orgs/{orgId}/sso | Remove the configuration, its domains, links and pending approvals |
| POST | /api/v1/orgs/{orgId}/sso/check | Fetch discovery and JWKS and report what was found (no response bodies) |
| POST | /api/v1/orgs/{orgId}/sso/test/start | Start a test sign-in (prompt=login); nothing is linked or signed in |
| POST | /api/v1/orgs/{orgId}/sso/test/result | The claims of a test sign-in (only for the admin who started it) |
| GET | /api/v1/orgs/{orgId}/scim | SCIM base URL, tokens, provisioned people (with status) and groups (owners and admins) |
| POST | /api/v1/orgs/{orgId}/scim/tokens | Create a SCIM bearer token (shown once; login in the last 10 minutes) |
| DELETE | /api/v1/orgs/{orgId}/scim/tokens/{id} | Revoke a SCIM token |
invitations
| Method | Path | Summary |
|---|---|---|
| GET | /api/v1/invitations/{token} | What an invitation is for (no session needed) |
| POST | /api/v1/invitations/accept | Accept an invitation |
recovery
| Method | Path | Summary |
|---|---|---|
| POST | /api/v1/recovery/code/start | Start an OPAQUE login with the recovery code |
| POST | /api/v1/recovery/code/finish | Finish the recovery-code login |
| POST | /api/v1/recovery/two-factor | Second factor of a recovery (TOTP or two-factor recovery code) |
| POST | /api/v1/recovery/complete/start | Start registering new credentials after a recovery |
| POST | /api/v1/recovery/complete/finish | Store new credentials, revoke every session and sign in the recovering device |
| POST | /api/v1/recovery/org/request | Ask an organization's recovery admins for recovery (signed out) |
| POST | /api/v1/recovery/org/status | Poll an organization recovery request |
| POST | /api/v1/recovery/org/cancel | Cancel an organization recovery request |
emergency
| Method | Path | Summary |
|---|---|---|
| GET | /api/v1/emergency | Emergency contacts granted and received |
| POST | /api/v1/emergency/grants | Invite an emergency contact |
| DELETE | /api/v1/emergency/grants/{id} | Remove an emergency contact (owner) or decline it (contact) |
| POST | /api/v1/emergency/grants/{id}/accept | Accept an invitation (contact) |
| POST | /api/v1/emergency/grants/{id}/confirm | Store the signed grant and the vault keys sealed to the contact (owner); also used to re-seal |
| POST | /api/v1/emergency/grants/{id}/request | Request access (contact); starts the waiting period |
| POST | /api/v1/emergency/grants/{id}/approve | Release access before the waiting period ends (owner) |
| POST | /api/v1/emergency/grants/{id}/deny | Deny a pending or released request (owner) |
| GET | /api/v1/emergency/grants/{id}/access | Sealed vault keys and the vaults' ciphertext (contact, after release) |
device-links
| Method | Path | Summary |
|---|---|---|
| POST | /api/v1/device-links | Start adding a device by code (signed-in device) |
| GET | /api/v1/device-links/{id} | Link status, with the new device's ephemeral key and MAC once claimed |
| DELETE | /api/v1/device-links/{id} | Cancel a link |
| POST | /api/v1/device-links/{id}/approve | Approve a claimed link with the sealed email and Secret Key |
| POST | /api/v1/device-links/claim | Claim a link from the new device |
| POST | /api/v1/device-links/poll | Poll a claimed link from the new device |
sso
| Method | Path | Summary |
|---|---|---|
| POST | /api/v1/sso/discover | Which organization's identity provider signs in an email domain |
| POST | /api/v1/sso/start | Start a sign-in (authorization code with PKCE) |
| GET | /api/v1/sso/callback | The identity provider's redirect |
| POST | /api/v1/sso/redeem | Turn a ticket into a single-use proof (10 minutes) |
| POST | /api/v1/sso/unlock | A trusted device trades a proof for a session and its sealed account key |
| POST | /api/v1/sso/device-requests | A new device asks a trusted device for approval (30 minutes) |
| POST | /api/v1/sso/device-requests/status | Poll an approval; returns the session and sealed key once |
scim
| Method | Path | Summary |
|---|---|---|
| GET | /api/v1/scim/v2/{resource} | SCIM 2.0 (RFC 7644) — ServiceProviderConfig, ResourceTypes, Schemas, Users, Groups |
agent-limit
| Method | Path | Summary |
|---|---|---|
| GET | /api/v1/agent-limit | The fair-use limit for AI agents and service accounts |
service-accounts
| Method | Path | Summary |
|---|---|---|
| GET | /api/v1/service-accounts | The account's service accounts, newest first |
| POST | /api/v1/service-accounts | Register a service account created by the client |
| PUT | /api/v1/service-accounts/{id} | Rename or change the expiry |
| DELETE | /api/v1/service-accounts/{id} | Delete the service account and its activity |
| PUT | /api/v1/service-accounts/{id}/grants | Add or renew vault grants |
| DELETE | /api/v1/service-accounts/{id}/grants/{vaultId} | Remove access to a vault (all key epochs) |
| POST | /api/v1/service-accounts/{id}/revoke | Revoke the token at once (sealed keys are deleted, agent grants revoked) |
| GET | /api/v1/service-accounts/{id}/events | What the service account did |
service-account
| Method | Path | Summary |
|---|---|---|
| GET | /api/v1/service-account | Everything the service account can read (service account authentication) |
| PUT | /api/v1/service-account/items/{id} | Create or update an item in a vault the service account may write to |
| DELETE | /api/v1/service-account/items/{id} | Delete an item (tombstone) |
| POST | /api/v1/service-account/agent-grants | Ask the owner for a grant (pbx mcp with a service account token) |
| GET | /api/v1/service-account/agent-grants/{id} | The owner's decision |
| POST | /api/v1/service-account/agent-events | Report an agent action of a service account |
agent-grants
| Method | Path | Summary |
|---|---|---|
| GET | /api/v1/agent-grants | Agent grant requests for this account (pending by default, `status=all` for 30 days) |
| POST | /api/v1/agent-grants | Ask for a grant (pbx mcp signed in as the account) |
| GET | /api/v1/agent-grants/{id} | The decision on a request (polled by the requesting broker) |
| POST | /api/v1/agent-grants/{id}/decision | Approve or deny, signed with the account key on the approving device |
| POST | /api/v1/agent-grants/{id}/revoke | End a pending or approved grant |
agent-events
| Method | Path | Summary |
|---|---|---|
| GET | /api/v1/agent-events | What agents did on behalf of this account |
| POST | /api/v1/agent-events | Report an agent action (the broker); never values |