REST API

Internal API, subject to change

This is the API the app’s own front end uses. It isn’t a versioned public API: endpoints and payloads can change between releases without notice. It’s documented here for operators, integrators testing a deployment, and troubleshooting.

Conventions

• Base path /api, on the same origin as the app. Request and response bodies are JSON unless noted.
• Authentication: Authorization: Bearer <session token>, as returned by the sign-in endpoints.
• Microsoft 365 features also need X-Entra-Token: <Entra access token for this API>.
• Errors look like {"error": {"message": "…", "code": "…", "details": …}}. See Errors.
• Who below: Public (no session), Signed in (any session), Member (a user of an organization with an active subscription), Owner (Tenant Owner), Super admin.

Health and configuration

Method	Path	Who	Purpose
GET	/api/health	Public	{"ok":true} when the database answers
GET	/api/config	Public	Brand, plans, billing mode, whether dev sign-in is on, and the Entra client ID and scope

Authentication

Method	Path	Who	Purpose
POST	/api/auth/signup	Public	Create an organization and its owner (name, email, password, organization); sends the confirmation email
POST	/api/auth/resend-verification	Public	Send the confirmation email again
POST	/api/auth/verify-email	Public	Confirm the email with the link token; returns a session
POST	/api/auth/login	Public	Email and password sign-in; returns a session
POST	/api/auth/forgot-password	Public	Email a reset link (same response whether or not the account exists)
POST	/api/auth/reset-password	Public	Set a new password with the reset token; signs out everywhere
POST	/api/auth/microsoft	Public	Exchange an Entra token (header or token in the body) for a session; may create the user when automatic joining is on
POST	/api/auth/dev-login	Public, development only	Sign in as an existing user by email
POST	/api/auth/logout	Signed in	End the current session
GET	/api/auth/me	Signed in	The user, their organization (plan, limits, usage, Microsoft connection) and capabilities

The sign-in endpoints are limited to 20 requests per minute per IP.

Organization settings

Method	Path	Who	Purpose
GET	/api/tenant	Owner	Organization name, status, automatic joining, Microsoft connection
PATCH	/api/tenant	Owner	Change name and/or autoProvision
GET	/api/tenant/microsoft/connect-url	Owner	URL of Microsoft’s admin-consent page (valid 15 minutes)
GET	/api/tenant/microsoft/callback	Public (redirect from Microsoft)	Finish admin consent; redirects to /admin/settings
POST	/api/tenant/microsoft/link	Owner + Entra token	Connect with the owner’s own work account
DELETE	/api/tenant/microsoft	Owner	Disconnect Microsoft 365

Users

Method	Path	Who	Purpose
GET	/api/users	Owner	Users, license count and limit
POST	/api/users	Owner	Add a user (email, name, role, notify)
PATCH	/api/users/:id	Owner	Change role and/or status (active, disabled)
DELETE	/api/users/:id	Owner	Remove a user
GET	/api/users/directory?q=	Owner + Entra token	Search the Microsoft 365 directory, marking people already added
GET	/api/directory?q=	Member + Entra token	Search the directory (choosing signers)

Billing

Method	Path	Who	Purpose
GET	/api/billing	Owner	Plan, status, period, limits, usage, plans, pack price, invoices
POST	/api/billing/checkout	Owner	Start a subscription (returns a Checkout URL) or switch plans (prorated)
POST	/api/billing/signing-packs	Owner	Buy 1–100 packs of extra signing requests (returns a Checkout URL)
POST	/api/billing/portal	Owner	URL of the Stripe customer portal
POST	/api/billing/fake/complete	Owner, simulated billing only	Complete a simulated checkout
POST	/api/billing/webhook	Stripe (signature checked)	Stripe events

Files (OneDrive and Teams)

All need Member + Entra token. File contents pass through and aren’t stored.

Method	Path	Purpose
GET	/api/files/locations	The user’s OneDrive and joined teams
GET	/api/files/teams/:teamId/channels	A team’s channels
GET	/api/files/teams/:teamId/channels/:channelId/folder	A channel’s files folder
GET	/api/files/drives/:driveId/items/:itemId/children	Folders, PDFs and images in a folder (root for the top)
GET	/api/files/drives/:driveId/items/:itemId/content	Download a file
PUT	/api/files/drives/:driveId/upload	Upload a PDF (application/pdf body): ?itemId= overwrites, or ?parentId=&name= creates (&replace=1 replaces an existing name)

Signing requests

Method	Path	Who	Purpose
POST	/api/envelopes	Member (Entra token optional)	Send a PDF for signature: multipart file + meta JSON (title, message, sequential, expiresInDays 1–365, reminderDays 1–30, recipients, fields, source)
GET	/api/envelopes?box=sent|inbox|all&status=&q=	Member	List requests (up to 200); all is the whole organization for owners
GET	/api/envelopes/:id	Sender, owner or recipient	Details, hashes and history
GET	/api/envelopes/:id/file?kind=original|signed	Sender, owner or recipient	Download the original or signed PDF
POST	/api/envelopes/:id/void	Sender or owner	Cancel (optional reason)
POST	/api/envelopes/:id/remind	Sender or owner (Entra token optional)	Remind signers whose turn it is
POST	/api/envelopes/:id/sign-link	Signer in the organization	Get your own signing link

Public signing

The link token authorizes these; limited to 60 requests per minute per IP.

Method	Path	Purpose
GET	/api/sign/:token	The request, this recipient, their fields and whether they can sign now; marks it viewed
GET	/api/sign/:token/document	The PDF, with completed signers’ fields drawn (the signed PDF once complete)
POST	/api/sign/:token/complete	Submit field values with consent: true
POST	/api/sign/:token/decline	Decline (optional reason)

Activity

Method	Path	Who	Purpose
POST	/api/activity	Signed in	Report up to 50 browser-side editor.* events
GET	/api/activity	Owner (own organization), Super admin (all; tenantId filter)	Events, filtered by actorId, action (or a prefix ending in .), q, from, to, paged with before and limit (max 1,000)
GET	/api/activity/summary	Same	Counts per action and per day, active people (default: last 30 days)
GET	/api/activity/export	Same	CSV of matching events (default 10,000 rows, limit up to 50,000)

Platform

All need Super admin.

Method	Path	Purpose
GET	/api/admin/stats	Platform totals and organizations per plan
GET	/api/admin/tenants?q=&status=	Organizations (up to 500)
GET	/api/admin/tenants/:id	One organization with usage and users
PATCH	/api/admin/tenants/:id	status, plan (including custom), customUsers, customSigningRequests, subscriptionStatus, addSigningCredits
GET	/api/admin/users?q=	Users across organizations (up to 500)
PATCH	/api/admin/users/:id	Enable or disable a (non-super-admin) user
POST	/api/admin/audit/verify	Verify the activity log’s hash chain

Development only

These return 404 when NODE_ENV=production.

Method	Path	Purpose
GET	/api/dev/emails?to=	Emails captured by the console transport
GET	/api/dev/users	Users available to the development sign-in