NeuPassbox ist da: im Web, auf dem Desktop, auf iPhone, Android und Ihrem eigenen Server. Kostenlos für Familien.Passbox ist da · Alle Apps ansehen
Zum Inhalt springen
Passbox
Passbox holen
GitHubPassbox holen

Entwickler

API

Der Passbox-Server ist eine schlichte HTTP-API. Web-App, Browser-Erweiterung, native Apps und CLI nutzen sie, und Ihre eigenen Werkzeuge können das auch.

openapi.yaml herunterladenAlle DokumenteQuelle auf GitHub

Diese Dokumentation gibt es nur auf Englisch.

Überblick

Die API ist in OpenAPI 3.1 beschrieben. Jeder Client verschlüsselt auf dem Gerät, die API sieht also nur Chiffretext, vom Client verpacktes Schlüsselmaterial und die Metadaten, die auf der Sicherheitsseite aufgeführt sind.

Version: 0.2.0 · OpenAPI 3.1

Konventionen und Fehler

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.

Endpunkte

Alle Endpunkte der aktuellen Version, nach Bereich gruppiert. Die Schemas für Anfragen und Antworten stehen in der OpenAPI-Datei.

health

MethodePfadBeschreibung
GET/healthLiveness check

meta

MethodePfadBeschreibung
GET/api/v1/metaPublic server information

auth

MethodePfadBeschreibung
POST/api/v1/auth/preloginKey derivation parameters for an email
POST/api/v1/auth/register/startStart an OPAQUE registration
POST/api/v1/auth/register/finishFinish the registration and create the account with its first vault
POST/api/v1/auth/login/startStart an OPAQUE login
POST/api/v1/auth/login/finishFinish the login and receive a session token
POST/api/v1/auth/login/two-factorComplete a login with its second factor
POST/api/v1/auth/logoutEnd the current session

account

MethodePfadBeschreibung
GET/api/v1/accountThe signed-in account
GET/api/v1/account/preferencesMail language and notification settings
PUT/api/v1/account/preferencesChange preferences (omitted fields stay)
GET/api/v1/account/two-factorTwo-factor authentication status
POST/api/v1/account/two-factor/totp/startCreate a TOTP secret for an authenticator app
POST/api/v1/account/two-factor/totp/confirmTurn the pending TOTP on with a first code
DELETE/api/v1/account/two-factor/totpRemove the authenticator app
POST/api/v1/account/two-factor/webauthn/register/startStart registering a security key or passkey
POST/api/v1/account/two-factor/webauthn/register/finishStore a verified security key
DELETE/api/v1/account/two-factor/webauthn/{id}Remove a security key
POST/api/v1/account/two-factor/recovery-codesReplace the recovery codes
POST/api/v1/account/two-factor/challengeStart checking a second factor while signed in
POST/api/v1/account/two-factor/disableTurn two-factor authentication off
GET/api/v1/account/keysThe account's own key pairs
PUT/api/v1/account/keysPublish the account's key pairs
GET/api/v1/account/recoveryRecovery status of the account (recovery code, organization escrows)
POST/api/v1/account/recovery-code/startStart registering the recovery code's OPAQUE record (login in the last 10 minutes)
POST/api/v1/account/recovery-codeStore the recovery code record and the account key wrapped with it (replaces an older code)
DELETE/api/v1/account/recovery-codeRemove the recovery code (login in the last 10 minutes)
GET/api/v1/account/trusted-devicesTrusted devices and pending approval requests
POST/api/v1/account/trusted-devicesTrust 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}/approveApprove a new device after comparing its code (login in the last 10 minutes)
POST/api/v1/account/trusted-devices/requests/{id}/denyDecline a new device

admin

MethodePfadBeschreibung
GET/api/v1/admin/settingsInstance settings and mail status
PUT/api/v1/admin/settingsChange the instance settings
GET/api/v1/admin/usersAccounts on the server
POST/api/v1/admin/users/{id}/disableDisable an account
POST/api/v1/admin/users/{id}/enableEnable a disabled account
POST/api/v1/admin/mail/testQueue a test mail
GET/api/v1/admin/invitesInvitations, newest first
POST/api/v1/admin/invitesInvite an email to create an account
DELETE/api/v1/admin/invites/{id}Withdraw an unused invitation
GET/api/v1/admin/eventsAdmin audit log, newest first

sync

MethodePfadBeschreibung
GET/api/v1/syncChanges since a cursor

vaults

MethodePfadBeschreibung
POST/api/v1/vaultsCreate a vault
PUT/api/v1/vaults/{id}Update vault metadata
GET/api/v1/vaults/{id}/access-requestWhether this account can open a vault, and its own request
POST/api/v1/vaults/{id}/access-requestsAsk the vault's managers for access
GET/api/v1/vaults/{id}/membersMembers and manifest chain of a shared vault (members)
POST/api/v1/vaults/{id}/membersShare with an account or group, or change a role (managers)
POST/api/v1/vaults/{id}/rotateRotate the vault key, removing members (managers)
PUT/api/v1/vaults/{id}/keys/{epoch}/wrappedStore the caller's own wrapped copy of a vault key
POST/api/v1/vaults/{id}/items/batchWrite up to 100 items of a vault (re-encryption after rotation)

items

MethodePfadBeschreibung
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}/versionsEarlier versions of an item
POST/api/v1/items/moveMove items into another vault

attachments

MethodePfadBeschreibung
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/usageAttachment limits and storage used

share-links

MethodePfadBeschreibung
GET/api/v1/share-linksThe account's share links that have not expired
POST/api/v1/share-linksCreate a share link
DELETE/api/v1/share-links/{id}End a share link

public

MethodePfadBeschreibung
GET/api/v1/public/share-links/{id}What the viewer needs before opening (no session)
POST/api/v1/public/share-links/{id}/openThe encrypted snapshot, for the access token (no session; counts a view)

access-requests

MethodePfadBeschreibung
GET/api/v1/access-requestsPending 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}/approveMark a request approved (after sharing the vault with the requester)
POST/api/v1/access-requests/{id}/denyDecline a request

icons

MethodePfadBeschreibung
GET/api/v1/icons/{domain}A website's icon, fetched by the server

breach

MethodePfadBeschreibung
GET/api/v1/breach/range/{prefix}Pwned Passwords range through the server (k-anonymity)
GET/api/v1/breach/emailsEmail breach monitoring of the account
POST/api/v1/breach/emailsMonitor an email address (sends a confirmation code)
DELETE/api/v1/breach/emails/{id}Stop monitoring an address
POST/api/v1/breach/emails/{id}/verifyConfirm an address with the mailed code
POST/api/v1/breach/emails/{id}/checkCheck a confirmed address now

breaches

MethodePfadBeschreibung
GET/api/v1/breaches/catalogThe breach catalogue (breached websites)
GET/api/v1/breaches/catalog/versionVersion of the breach catalogue

keys

MethodePfadBeschreibung
GET/api/v1/keys/headSigned head of the key log
GET/api/v1/keys/logEntries of the key log
GET/api/v1/keys/{accountId}Look up an account's current key with a proof

orgs

MethodePfadBeschreibung
GET/api/v1/orgsThe account's organizations
POST/api/v1/orgsCreate 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-keyRotate the organization key (admins)
GET/api/v1/orgs/{orgId}/invitationsPending invitations (admins)
POST/api/v1/orgs/{orgId}/invitationsInvite 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}/confirmConfirm an accepted member (admins)
POST/api/v1/orgs/{orgId}/members/{accountId}/suspendSuspend a member (admins; not cryptographic)
POST/api/v1/orgs/{orgId}/members/{accountId}/reactivateReactivate a suspended member (admins)
GET/api/v1/orgs/{orgId}/groupsGroups of an organization (confirmed members)
POST/api/v1/orgs/{orgId}/groupsCreate 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}/membersAdd a group member (one sealing of the group key)
POST/api/v1/orgs/{orgId}/groups/{groupId}/rotateRotate a group's key, removing members (admins)
POST/api/v1/orgs/{orgId}/vaultsCreate a shared vault (owners and admins)
DELETE/api/v1/orgs/{orgId}/recoveryTurn organization recovery off for everyone
GET/api/v1/orgs/{orgId}/recoveryOrganization recovery key, grants and the caller's escrow
POST/api/v1/orgs/{orgId}/recovery/keysCreate the organization recovery key (owners and admins)
POST/api/v1/orgs/{orgId}/recovery/grantsSeal the recovery key to another admin
PUT/api/v1/orgs/{orgId}/recovery/escrowOpt in to organization recovery (signed escrow of the account key)
DELETE/api/v1/orgs/{orgId}/recovery/escrowWithdraw from organization recovery
GET/api/v1/orgs/{orgId}/recovery/requestsPending recovery requests (recovery admins)
POST/api/v1/orgs/{orgId}/recovery/requests/{requestId}/approveApprove a recovery request (after an out-of-band identity check)
POST/api/v1/orgs/{orgId}/recovery/requests/{requestId}/denyDeny a recovery request
GET/api/v1/orgs/{orgId}/ssoThe organization's OIDC configuration, or null (owners and admins)
PUT/api/v1/orgs/{orgId}/ssoCreate or replace the configuration (team organizations)
DELETE/api/v1/orgs/{orgId}/ssoRemove the configuration, its domains, links and pending approvals
POST/api/v1/orgs/{orgId}/sso/checkFetch discovery and JWKS and report what was found (no response bodies)
POST/api/v1/orgs/{orgId}/sso/test/startStart a test sign-in (prompt=login); nothing is linked or signed in
POST/api/v1/orgs/{orgId}/sso/test/resultThe claims of a test sign-in (only for the admin who started it)
GET/api/v1/orgs/{orgId}/scimSCIM base URL, tokens, provisioned people (with status) and groups (owners and admins)
POST/api/v1/orgs/{orgId}/scim/tokensCreate 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

MethodePfadBeschreibung
GET/api/v1/invitations/{token}What an invitation is for (no session needed)
POST/api/v1/invitations/acceptAccept an invitation

recovery

MethodePfadBeschreibung
POST/api/v1/recovery/code/startStart an OPAQUE login with the recovery code
POST/api/v1/recovery/code/finishFinish the recovery-code login
POST/api/v1/recovery/two-factorSecond factor of a recovery (TOTP or two-factor recovery code)
POST/api/v1/recovery/complete/startStart registering new credentials after a recovery
POST/api/v1/recovery/complete/finishStore new credentials, revoke every session and sign in the recovering device
POST/api/v1/recovery/org/requestAsk an organization's recovery admins for recovery (signed out)
POST/api/v1/recovery/org/statusPoll an organization recovery request
POST/api/v1/recovery/org/cancelCancel an organization recovery request

emergency

MethodePfadBeschreibung
GET/api/v1/emergencyEmergency contacts granted and received
POST/api/v1/emergency/grantsInvite an emergency contact
DELETE/api/v1/emergency/grants/{id}Remove an emergency contact (owner) or decline it (contact)
POST/api/v1/emergency/grants/{id}/acceptAccept an invitation (contact)
POST/api/v1/emergency/grants/{id}/confirmStore the signed grant and the vault keys sealed to the contact (owner); also used to re-seal
POST/api/v1/emergency/grants/{id}/requestRequest access (contact); starts the waiting period
POST/api/v1/emergency/grants/{id}/approveRelease access before the waiting period ends (owner)
POST/api/v1/emergency/grants/{id}/denyDeny a pending or released request (owner)
GET/api/v1/emergency/grants/{id}/accessSealed vault keys and the vaults' ciphertext (contact, after release)

device-links

MethodePfadBeschreibung
POST/api/v1/device-linksStart 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}/approveApprove a claimed link with the sealed email and Secret Key
POST/api/v1/device-links/claimClaim a link from the new device
POST/api/v1/device-links/pollPoll a claimed link from the new device

sso

MethodePfadBeschreibung
POST/api/v1/sso/discoverWhich organization's identity provider signs in an email domain
POST/api/v1/sso/startStart a sign-in (authorization code with PKCE)
GET/api/v1/sso/callbackThe identity provider's redirect
POST/api/v1/sso/redeemTurn a ticket into a single-use proof (10 minutes)
POST/api/v1/sso/unlockA trusted device trades a proof for a session and its sealed account key
POST/api/v1/sso/device-requestsA new device asks a trusted device for approval (30 minutes)
POST/api/v1/sso/device-requests/statusPoll an approval; returns the session and sealed key once

scim

MethodePfadBeschreibung
GET/api/v1/scim/v2/{resource}SCIM 2.0 (RFC 7644) — ServiceProviderConfig, ResourceTypes, Schemas, Users, Groups

agent-limit

MethodePfadBeschreibung
GET/api/v1/agent-limitThe fair-use limit for AI agents and service accounts

service-accounts

MethodePfadBeschreibung
GET/api/v1/service-accountsThe account's service accounts, newest first
POST/api/v1/service-accountsRegister 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}/grantsAdd 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}/revokeRevoke the token at once (sealed keys are deleted, agent grants revoked)
GET/api/v1/service-accounts/{id}/eventsWhat the service account did

service-account

MethodePfadBeschreibung
GET/api/v1/service-accountEverything 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-grantsAsk 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-eventsReport an agent action of a service account

agent-grants

MethodePfadBeschreibung
GET/api/v1/agent-grantsAgent grant requests for this account (pending by default, `status=all` for 30 days)
POST/api/v1/agent-grantsAsk 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}/decisionApprove or deny, signed with the account key on the approving device
POST/api/v1/agent-grants/{id}/revokeEnd a pending or approved grant

agent-events

MethodePfadBeschreibung
GET/api/v1/agent-eventsWhat agents did on behalf of this account
POST/api/v1/agent-eventsReport an agent action (the broker); never values