HTTP API

The Worker's API, as used by the extension and the share page. It is not a public, versioned API: it changes with the extension, and only the extension from the same release is guaranteed to work with it.

Conventions

• Base URL: https://<worker>/api.
• Bodies: JSON in, JSON out. Timestamps are Unix seconds. Binary values (ciphertext, nonces, keys, salts) are standard base64 with padding, except where noted as base64url.
• Authentication: Authorization: Bearer <token>, where the token comes from register or login. There are no cookies, so there is no CSRF surface.
• CORS: only chrome-extension:// and moz-extension:// origins are allowed. The share page calls the API from the same origin and needs no CORS.
• Sealed value: an object { "ciphertext": string, "nonce": string } produced by AES-256-GCM with a 12-byte nonce.
• Errors: every failure has the shape below. code is stable and meant for programs; error is an English sentence for humans; params holds values for the localized message.

``json { "code": "auth.rate_limited", "error": "Too many attempts, try again later", "params": { "seconds": 840 } } ``

Rate limits per endpoint are listed in Limits. Any endpoint can also return 429 server.rate_limited and 500 server.error. Any endpoint that takes a body returns 400 auth.invalid_body when the body is not a JSON object (malformed JSON, an array, a scalar or nothing at all), before it looks at any field.

Server

GET /api/config

What the server requires at sign-up. No authentication.

{ "registration": "token", "emailVerification": false }

registration is token or open. emailVerification is true when a sender and a mail provider are configured. When Turnstile is configured, the response also carries turnstileSiteKey, and register, verify-email, recover/email, recover/start and POST /api/shares/:id/code need a token in the X-Turnstile-Token header, or answer 403 auth.bot_check_failed. When PRIVACY_URL is set, the response carries it as privacyUrl; clients link the privacy policy only when it is present.

GET /api/time

The server clock, used by the extension to correct 2FA codes on a machine whose clock is off.

{ "serverTime": 1791820800 }

GET /api/logo?domain=<hostname>

Session required. Returns the website icon for a hostname as an image, fetched from DuckDuckGo or, failing that, Google, and cached at the edge for 7 days. The hostname must be a plain domain name; anything else, or a site without an icon, answers 404 server.not_found. Images over 64 KiB are refused. The response is Cache-Control: private, no-store, so browsers keep no copy.

Accounts

POST /api/auth/verify-email

Send a 6-digit sign-up code to an address. Only meaningful when emailVerification is on.

An address that already has an account receives a "you already have an account" email instead of a code, and the response is the same, so the endpoint does not reveal which addresses are registered. The account lookup and the email happen after the response is sent, so a failed send is logged, not returned, and the timing is the same either way.

POST /api/auth/register

Create an account. The client derives every key; the server receives only the auth key and the wrapped vault key.

Header X-Registration-Token is required when registration is token, unless inviteId names a pending invitation for the same address: an invitation is the admin's consent, so invited people can sign up on a token-only server.

Without email verification, an address that already has an account gets a 201 with a random accountId and a token that is not stored, and nothing changes, so the response does not reveal that the address is taken.

POST /api/auth/prelogin

The KDF parameters to derive the auth key with, before signing in.

Request { "email": string }. Response:

{ "kdf": { "type": "pbkdf2-sha256", "iterations": 600000, "salt": "…" } }

An unknown address gets plausible parameters derived from a server secret, the same on every call, so the response does not reveal whether an account exists.

POST /api/auth/login

Failures are throttled per address and network: five are free, then each one doubles the wait, from 5 seconds up to an hour. After 20 failures in an hour on one address from any network, every attempt on it is also slowed, by up to 5 seconds. There is no hard lock. A 200 adds "upgradeKdf": true when the account uses fewer than 600,000 iterations; the client then re-wraps the vault key through change-password with keepSession.

When the account has two-factor authentication on, a correct authKey returns 200 { "twoFactor": "required", "challenge": string, "expiresAt": number } instead, with no token and no wrapped key. A client that does not know this field finds no token and fails closed. Wrong credentials answer exactly as above, so the response never reveals whether 2FA is on before the password is right.

A correct password for a member (not an owner or admin) of an organization that requires single sign-on answers 403 auth.sso_required with params.identifier, the organization identifier to start SSO with. The same check runs again in login/2fa.

POST /api/auth/login/2fa

Unauthenticated, rate-limited like login, and counted against the same throttle. Request { "challenge": string, "code": string }, where code is a 6-digit TOTP code (RFC 6238, SHA-1, 30 s, ±1 step) or a backup code (xxxxx-xxxxx; case, spaces and dashes are ignored). A TOTP code is accepted once; a backup code once ever.

A challenge lasts five minutes, is single use, and is dropped after five wrong codes.

GET /api/auth/resume-key

Authenticated. Returns { "resumeKey": "<base64>" }, a random 32-byte key that belongs to this session and is created on first request. The extension seals the vault key under it so the vault reopens after a browser restart; deleting the session deletes the key.

PUT /api/auth/pin

Authenticated. Body { "verifier": "<base64, 32 bytes>" }. Turns on PIN unlock for this session: stores a keyed hash of the verifier, creates a random 32-byte pinKey, resets the attempt count and returns { "pinKey": string }. The extension derives the verifier and a second, local half from the PIN with PBKDF2; the server never sees the PIN or the local half.

POST /api/auth/pin/unlock

Authenticated with the session the PIN belongs to. Body { "verifier": ... }.

Each call spends a try before comparing, in one statement, so parallel guesses cannot exceed five.

DELETE /api/auth/pin

Authenticated. Turns PIN unlock off for this session. Returns { "ok": true }.

PUT /api/auth/biometric

Authenticated. Body { credentialId, publicKey, algorithm, rpId, origin }: the credential a platform authenticator (Touch ID, Windows Hello) just created on an extension page, its public key as base64url SPKI, -7 (ES256) or -257 (RS256), and the extension's origin chrome-extension://<id> with that id as RP ID. Anything else is 400 auth.invalid_body. Returns { "bioKey": string }, a random 32-byte key for this session.

POST /api/auth/biometric/challenge

Authenticated. Returns { challenge, credentialId }: a one-time base64url challenge that expires in two minutes, or 410 auth.biometric_off. The session keeps its five most recent open challenges, so a second request does not void a prompt that is still on screen.

POST /api/auth/biometric/unlock

Authenticated. Body { clientDataJSON, authenticatorData, signature } from navigator.credentials.get. The challenge named in clientDataJSON must be one of the session's open challenges, and it is spent before anything else is checked, then the server verifies the type, challenge, origin, RP ID hash, the user present and user verified flags, and the signature against the registered key. Returns { "bioKey": string }, or 403 auth.biometric_failed.

DELETE /api/auth/biometric

Authenticated. Turns biometric unlock off for this session.

POST /api/auth/logout

Authenticated. Revokes the current session. Returns { "ok": true }.

POST /api/auth/change-password

Authenticated. Replaces the KDF parameters, auth key and wrapped vault key in one step, then revokes every session of the account.

Returns { "ok": true }, or 400 for a malformed field and 403 auth.invalid_credentials when currentAuthKey is wrong.

POST /api/auth/delete-account

Authenticated. Request { "currentAuthKey": string }. Deletes the account, its items and its sessions. Returns { "ok": true }, or 403 auth.invalid_credentials.

Shares are not linked to accounts, so links already sent keep working until they expire or run out of views.

Recovery code

A recovery code is 20 random bytes, shown as 32 base32 characters in groups of four. The client derives two keys from it with HKDF-SHA256 (salt personal-vault/recovery/v1): wrap seals the vault key, and auth is sent to the server, which keeps only an HMAC of it, as for the auth key. The server cannot open the vault key with what it stores.

GET /api/account/recovery

Authenticated. Returns { "createdAt": number | null }.

PUT /api/account/recovery

Authenticated. Creates or replaces the recovery code; the previous one stops working.

Returns { "createdAt": number }, or 403 auth.invalid_credentials.

DELETE /api/account/recovery

Authenticated. Request { "currentAuthKey": string }. Removes the recovery code. Returns { "ok": true }, or 403 auth.invalid_credentials.

POST /api/auth/recover/email

Unauthenticated, rate-limited per IP and throttled per address and network like login, with counters separate from sign-in. Request { "email", "recoveryAuthKey", "locale"? }. Checks the recovery code and, when the server can send email, emails a 6-digit code to the account's address. Returns { "required": boolean }; required is false on a server without email, where the next two calls take no emailCode. Errors: 401 auth.invalid_recovery_code for a wrong code or an unknown address alike, 429 auth.code_cooldown within a minute of the last code.

POST /api/auth/recover/start

Unauthenticated, rate-limited like recover/email. Request { "email", "recoveryAuthKey", "emailCode"? }. Returns { "wrappedVaultKey": sealed }, the vault key sealed under the code. Errors: 401 auth.invalid_recovery_code, 400 auth.invalid_code for a wrong emailed code (five tries), 400 auth.code_expired after 15 minutes.

POST /api/auth/recover/finish

Unauthenticated. Sets a new master password and a new recovery code in one step, then revokes every session and emails the owner when the server can send email. The code used stops working.

Returns { "ok": true }, or the errors of recover/start. When the account had two-factor authentication on, the recovery code bypasses it, turns it off and deletes the backup codes; the response adds "twoFactorDisabled": true and the owner gets a separate email.

Two-factor authentication

The TOTP secret is stored encrypted under a key derived from AT_REST_SECRET; backup codes are stored as keyed hashes. Every request below is authenticated and needs currentAuthKey; locale (en or vi) is optional.

GET /api/account/2fa

Returns { "enabled": boolean, "enabledAt": number | null, "backupCodesLeft": number }.

POST /api/account/2fa/setup

Request { "currentAuthKey" }. Returns { "secret": string, "uri": string }, the base32 secret and its otpauth:// URI. The secret waits 15 minutes for enable. 409 two_factor.already_enabled when it is already on.

POST /api/account/2fa/enable

Request { "currentAuthKey", "code" } with a current code from the new secret. Returns { "enabledAt": number, "backupCodes": string[] } (ten codes, shown once), signs out every other session and emails the owner. Errors: 400 auth.invalid_2fa, 400 two_factor.setup_expired.

POST /api/account/2fa/disable

Request { "currentAuthKey", "code" }, where code is a TOTP or backup code. Returns { "ok": true } and emails the owner. Wrong codes answer 401 auth.invalid_2fa and are throttled per address and network.

POST /api/account/2fa/backup-codes

Request { "currentAuthKey", "code" }. Returns { "backupCodes": string[] }; every earlier backup code stops working.

Account key pair

Every account has an ECDH P-256 key pair so that team keys can be wrapped for it (see Teams and CI secrets). The extension creates it the first time the vault opens.

GET /api/account/identity

Authenticated. Returns { "identity": { publicKey, wrappedPrivateKey } }, or { "identity": null } before one exists. wrappedPrivateKey is sealed under the vault key; the server cannot open it.

PUT /api/account/identity

Authenticated. Body { publicKey, wrappedPrivateKey }. Stores the pair once; 409 account.identity_exists afterwards, so a stolen session cannot swap in a key its holder controls.

Organizations

All authenticated. Membership and roles live in D1; teams, wrapped team keys and the audit log live in the organization's Durable Object (org:<id>), which checks the caller's role again against its own copy. An organization the caller is not in answers 404 orgs.not_found, never 403, so its existence does not leak.

Project and secret writes carry the team's key generation; a write for an older one gets 409 orgs.stale_team_key, and every write is refused with 409 orgs.rekey_required while the team waits for a new key after someone left.

Single sign-on

Commercial; see Single sign-on. Every route below answers 403 license.required when the organization is neither on the enterprise plan nor covered by a valid LICENSE_KEY, except the read-only overview, which reports the licence instead.

POST /api/sso/prepare

No session; rate-limited per network.

The server stores a one-time state (10 minutes) with the sealed PKCE code verifier it will send to the provider, the nonce and the client challenge. authorizeUrl carries response_type=code, scope=openid email profile, state, nonce, code_challenge (S256) and the fixed redirect_uri=<server>/api/sso/callback.

GET /api/sso/callback?code=…&state=…

The provider's redirect. An unknown, used or expired state answers 400 sso.expired as JSON and redirects nowhere. Otherwise the state is consumed and the browser is sent to the stored returnTo with a fragment: #sso_grant=<grant> on success, or #sso_error=<code> with sso.failed, sso.email_unverified, sso.email_not_allowed, sso.not_found or license.required. The grant is single-use and lives two minutes. A state from POST /api/orgs/:id/sso/link never yields a grant: it ends with #sso_link=linked, or #sso_link_error=<code> with the codes above, sso.link_email_mismatch or sso.link_taken.

POST /api/sso/session

Request { "grant": string, "clientVerifier": string, "locale"?: "en" | "vi" }. The grant is consumed even when the verifier is wrong.

Account two-factor authentication is not asked for here; the identity provider's sign-in stands in for it.

Organization settings

All need an owner or admin session.

Each change is recorded in the organization's audit log. Every write returns the same overview as GET.

Linking a member's account

Any member's session. For addresses that are not on a verified domain.

Team vaults

GET /api/vaults

Every team vault the caller can read, across all their organizations: one entry per team they are in, with orgId, orgName, teamId, name, generation, rekeyNeeded, the team key wrapped for the caller (wrappedKey) and every item as { id, sealed, updatedAt, updatedBy }. Admins who are not in a team do not get its vault. Writes go through the organization routes above.

CI

POST /api/ci/secrets

No session. Authorization: Bearer <GitHub Actions OIDC token> requested with this server's origin as the audience, and a body { "link": "<org>.<link>" }. Returns { projectId, environmentId, generation, wrappedKey, secrets: [{ id, sealed }] }: the environment key wrapped for the repository and the sealed values, nothing readable. 401 ci.unauthorized for a missing or invalid token, 403 ci.forbidden when the repository, branch or GitHub environment does not match the link. Rate limited per link.

Items

All item endpoints require authentication. An item is a single sealed blob; the server never sees its fields.

GET /api/items?since=<timestamp>

Changes since a cursor, oldest first. Omit since (or send 0) for everything.

{
  "serverTime": 1791820799,
  "items": [
    { "id": "…", "ciphertext": "…", "nonce": "…", "updatedAt": 1791820700, "deletedAt": null },
    {
      "id": "…",
      "ciphertext": null,
      "nonce": null,
      "updatedAt": 1791820750,
      "deletedAt": 1791820750
    }
  ]
}

Use serverTime as the next since. A deleted item comes back as a tombstone with deletedAt set and no ciphertext.

PUT /api/items/:id

Create or replace an item. :id is a UUID chosen by the client. Body: a sealed value, ciphertext at most 64 KiB.

Writing to a deleted item's id restores it.

With ?ifUpdatedAt=<number> the write is conditional: it replaces the item only if it still exists and its updatedAt equals that number, and never creates or restores one. Otherwise it returns 409 items.conflict. The extension uses it for background writes such as recording when a login was last used, so they cannot overwrite an edit or undo a deletion made on another device.

POST /api/items/batch

Create up to 100 new items in one request, for imports. Body: { "items": [{ "id": uuid, "ciphertext": string, "nonce": string }] }.

Returns { "updatedAt": number, "created": string[] }. An id that already exists, in this account or another, is left untouched and is missing from created. Errors: 400 items.invalid_id, 400 items.invalid_payload (empty, more than 100, or a malformed item), 403 items.quota_exceeded when the batch would take the account past its item limit. The whole batch counts as one write for rate limiting.

DELETE /api/items/:id

Replaces the item with a tombstone. Returns { "id": string, "deletedAt": number }, or 404 items.not_found.

Shares

POST /api/shares

Authenticated. Store an encrypted share. The key stays in the link fragment and never reaches the server.

id and revokeToken are base64url. The server stores only a hash of revokeToken; keep it to revoke or check the share later.

The link is https://<worker>/s/<id>#<key>, where <key> is the base64url share key, followed by .p when the link also needs a passphrase.

POST /api/shares/status

Authenticated. Look up shares you created. Request:

{ "shares": [{ "id": "…", "revokeToken": "…" }] }

Up to 50 entries. Each answer is either { "id", "active": true, "expiresAt", "viewsLeft" } or { "id", "active": false }. viewsLeft is null for a link without a view limit. A wrong token reads as inactive.

DELETE /api/shares/:id

Authenticated. Header X-Revoke-Token: <token>. Deletes the share at once. Returns { "ok": true }, or 404 shares.gone for an unknown id or a wrong token.

GET /api/shares/:id

No authentication. Spends one view and returns the ciphertext:

{ "ciphertext": "…", "nonce": "…", "expiresAt": 1791907200, "viewsLeft": 0 }

viewsLeft is null when the link has no view limit, and 0 when this was the last view.

POST /api/shares/:id/code

No authentication. Request { "email": string, "locale"?: "en" | "vi" }. Emails a 6-digit code if the address is a recipient of the share.

Always returns { "ok": true }, whether or not the address is allowed, the share exists, a cooldown applies, or sending failed. Anything else would let someone test addresses against the recipient list.

POST /api/shares/:id/open

No authentication. Request { "email": string, "code": string }. On success, spends one view and returns the same body as GET /api/shares/:id.

Errors: 400 shares.invalid_code, 400 shares.code_expired, 404 shares.gone.

Pages

Error codes