Endpoints

All operations, generated from the same OpenAPI document as the interactive reference (each path links to it). Base URL: https://bonafide-api.republic.global. Download the document as JSON or YAML to generate a client or import it into Postman or Insomnia.

Auth is what the operation accepts: an API key (Authorization: Bearer bf_… or x-api-key), a dashboard session (the dashboard’s own calls), a signer token (/v1/signing/*), a viewer token (/v1/viewer/*, from the link in a viewer’s email), or nothing.

Templates

Endpoint	What it does	Auth
POST /v1/templates	Create a template	API key or dashboard
GET /v1/templates	List templates	API key or dashboard
GET /v1/templates/{id}	Get a template	API key or dashboard
DELETE /v1/templates/{id}	Delete a template that was never used by an envelope or signing link	API key or dashboard
POST /v1/templates/{id}/files	Upload the source PDF (or a .docx, converted to PDF to keep the exact Word layout)	API key or dashboard
POST /v1/templates/{id}/import	Convert a Word document (.docx) into an editable Document-mode draft body (nothing is stored)	API key or dashboard
PUT /v1/templates/{id}/draft	Create or replace the draft version	API key or dashboard
POST /v1/templates/{id}/publish	Publish the draft as a new immutable version	API key or dashboard
GET /v1/templates/{id}/versions	List versions (newest first)	API key or dashboard
GET /v1/templates/{id}/versions/{version}	Get a version (number, "latest" or "draft")	API key or dashboard
GET /v1/templates/{id}/versions/{version}/document	The base PDF of a version (number, "latest" or "draft"); drafts give the uploaded original unless ?edited=true	API key or dashboard
POST /v1/templates/{id}/versions/{version}/render	Render a watermarked PREVIEW PDF with variables	API key or dashboard

Envelopes

Endpoint	What it does	Auth
POST /v1/envelopes	Create and send an envelope from a template, with optional send-time routing, CC, viewers and reminders (dry_run=true validates and renders only)	API key or dashboard
GET /v1/envelopes	List envelopes	API key or dashboard
GET /v1/envelopes/{id}	Get an envelope	API key or dashboard
GET /v1/envelopes/{id}/document	Download the rendered original, the sealed PDF or the standalone certificate of completion	API key or dashboard
POST /v1/envelopes/{id}/void	Void an envelope in progress	API key or dashboard
POST /v1/envelopes/{id}/viewers	Add viewers to an envelope in progress (read-only status page, emailed right away; limited per envelope by plan)	API key or dashboard
DELETE /v1/envelopes/{id}/viewers/{viewer}	Revoke a viewer: every status link they were sent stops working	API key or dashboard
POST /v1/envelopes/{id}/recipients/{recipient}/resend	Email the recipient a fresh signing link (their turn only; at most once a minute)	API key or dashboard
GET /v1/envelopes/{id}/events	The envelope audit trail with hash-chain verification	API key or dashboard
GET /v1/envelopes/{id}/events/stream	Server-sent events for one envelope (Last-Event-ID = seq resumes)	API key or dashboard

Signing

Endpoint	What it does	Auth
POST /v1/envelopes/{id}/sessions	Mint a short-lived, single-use signing session for a recipient (embedded or hosted)	API key or dashboard
POST /v1/signing/exchange	Exchange a session token (email link / embed) for a short-lived access token	Public
GET /v1/signing/session	Load the signer view	Signer token
GET /v1/signing/document	The PDF to display to the signer	Signer token
POST /v1/signing/otp	Send a one-time code (email; SMS if enabled for the org)	Signer token
POST /v1/signing/otp/verify	Verify the one-time code	Signer token
POST /v1/signing/attachments	Upload a file for an attachment field (multipart: field, file)	Signer token
POST /v1/signing/submit	Submit field values, signature and consent	Signer token
POST /v1/signing/decline	Decline to sign (ends the envelope)	Signer token

Signing links

Endpoint	What it does	Auth
GET /v1/links/{id}	Public description of an always-on link	Public
POST /v1/links/{id}/start	Visitor details → email OTP (rate limited)	Public
POST /v1/links/{id}/verify	Verify the OTP; creates the envelope and a signing session	Public
POST /v1/signing-links	Create an always-on signing link	API key or dashboard
GET /v1/signing-links	List signing links	API key or dashboard
PATCH /v1/signing-links/{id}	Change, pause or resume a link	API key or dashboard
DELETE /v1/signing-links/{id}	Delete a link (envelopes it created stay)	API key or dashboard

Viewers

Endpoint	What it does	Auth
POST /v1/viewer/exchange	Exchange a viewer link token (from the viewer email) for a short-lived access token	Public
GET /v1/viewer/envelope	Read-only envelope status for a viewer (the first open is recorded in the audit trail)	Viewer token
GET /v1/viewer/document	The document, when the sender let viewers see it (the sealed PDF once sealed)	Viewer token
GET /v1/viewer/stream	Server-sent `update` pings when the envelope changes (refetch the status); access token in the query	Viewer token

Webhooks

Endpoint	What it does	Auth
POST /v1/webhook-endpoints	Register a webhook endpoint (Standard Webhooks; the secret is returned once)	API key or dashboard
GET /v1/webhook-endpoints	List webhook endpoints with delivery health	API key or dashboard
GET /v1/webhook-endpoints/{id}	Get a webhook endpoint	API key or dashboard
PATCH /v1/webhook-endpoints/{id}	Change URL, events, description or pause	API key or dashboard
DELETE /v1/webhook-endpoints/{id}	Delete a webhook endpoint	API key or dashboard
POST /v1/webhook-endpoints/{id}/secret	Reveal the signing secret	Dashboard only
POST /v1/webhook-endpoints/{id}/secret/rotate	Rotate the signing secret (the old one also signs for 24 h)	API key or dashboard
GET /v1/webhook-endpoints/{id}/deliveries	Recent delivery attempts	API key or dashboard
POST /v1/webhook-endpoints/{id}/test	Send a `webhook.test` ping	API key or dashboard
POST /v1/events/{id}/redeliver	Deliver an envelope event to an endpoint again	API key or dashboard

API keys

Endpoint	What it does	Auth
POST /v1/api-keys	Create an org API key (bf_live_/bf_test_); shown once	Dashboard only
GET /v1/api-keys	List org API keys	Dashboard only
DELETE /v1/api-keys/{id}	Revoke an API key	Dashboard only

Directory

Endpoint	What it does	Auth
GET /v1/scim	SCIM endpoint, token state and provisioned users	Dashboard only
POST /v1/scim/token	Create (or replace) the SCIM bearer token; shown once	Dashboard only
DELETE /v1/scim/token	Revoke the SCIM token (provisioning stops)	Dashboard only

Organization

Endpoint	What it does	Auth
GET /v1/organization/settings	Feature flags (e.g. SMS add-on)	API key or dashboard
GET /v1/organization/email-branding	Email branding settings and what the plan allows	API key or dashboard
PUT /v1/organization/email-branding	Change email branding (display name, custom message; footer and Powered-by removal by plan)	API key or dashboard
POST /v1/organization/email-branding/preview	Render a sample email for the organization (optionally with unsaved branding); the plan's limits apply	API key or dashboard
POST /v1/organization/logo	Upload a logo (multipart `file`, PNG/JPEG/SVG/WebP ≤ 512 KB) → public URL to store via Better Auth organization.update	Dashboard only
GET /v1/public/logos/{org}/{file}	A public organization logo	Public
GET /v1/usage	Metered usage for a billing period (YYYY-MM)	API key or dashboard

SSO

Endpoint	What it does	Auth
GET /v1/sso/discover	Does this email sign in with company SSO? (public, rate limited)	Public
GET /v1/sso/connections	Settings and health of the org's SSO connections	Dashboard only
GET /v1/sso/connections/{providerId}	Settings and health of one connection	Dashboard only
PUT /v1/sso/connections/{providerId}/settings	Enforcement, default role and JIT provisioning	Dashboard only
POST /v1/sso/connections/{providerId}/tests	Start a test login; open `url` in a popup and poll the test	Dashboard only
GET /v1/sso/connections/{providerId}/tests/{testId}/start	Redirect to the IdP for a test login (popup)	Dashboard only
GET /v1/sso/connections/{providerId}/tests/{testId}	Outcome of a test login	Dashboard only
POST /v1/sso/saml-metadata	Fetch an IdP metadata URL server-side	Dashboard only
GET /v1/sso/audit	SSO and SCIM administration audit trail (newest first)	Dashboard only

Billing

Endpoint	What it does	Auth
GET /v1/billing	Plan, usage this period, upcoming invoice and entitlements	API key or dashboard
GET /v1/billing/subscription	Plan and usage (subset of GET /v1/billing)	API key or dashboard
POST /v1/billing/checkout	Start a subscription (Stripe Checkout URL) or switch an existing one in place	Dashboard only
POST /v1/billing/portal	Stripe Customer Portal URL (cards, invoices, tax IDs, cancel)	Dashboard only
POST /v1/billing/webhooks/stripe	Stripe webhook receiver (Stripe-Signature verified)	Public

Verification

Endpoint	What it does	Auth
GET /.well-known/bona-fide/keys.json	Ed25519 public keys that sign evidence anchors, with validity periods (public)	Public
GET /v1/public/anchors	Signed evidence anchors, newest first (public)	Public
GET /v1/public/anchors/latest	The latest signed evidence anchor (public)	Public
GET /v1/public/anchors/{sequence}	A signed evidence anchor by sequence number (public)	Public
POST /v1/public/verify	Look up a document by SHA-256: envelope summary, Merkle leaf, inclusion proof and signed anchor (public; hash the file locally)	Public