Ollasync API

A blind end-to-end-encrypted messaging engine you sell as infrastructure. Your servers store and order ciphertext; they never hold keys or see plaintext. Clients (web, iOS, Android, CLI — any language) run an open MLS (RFC 9420) stack and exchange opaque blobs through these endpoints.

There are three planes: the Account API (you, the customer — sign up, get API keys, mint tokens, see usage), the Room & messaging API (your end-users — the blind transport), and the Deal-room workflow (parties, NDA gating, a role-gated document vault) layered on top.

Base URL & format#

All endpoints live under your deployment's HTTPS origin. Examples on this page use your current origin:

__BASE__/v1/...

• TLS 1.3 only; HTTP/2.
• Requests & responses are JSON (Content-Type: application/json), except signed attachment PUT/GET.
• Binary MLS material (key packages, message blobs) is base64 (standard encoding) inside JSON.
• IDs (room, member) are URL-safe slugs: letters, digits, -, _, . (validated server-side).
• Timestamps are Unix seconds (integers).
• Liveness: GET /healthz → 200. Prometheus metrics at /metrics (bearer DEALROOM_METRICS_TOKEN, required — 401 until it is set; never public).

Authentication#

Every non-public call carries a bearer credential. There are three kinds, each for a different actor:

Room tokens are short-lived HS256 JWTs scoped to a single room and member. You mint them server-side from an API key (below) — the standard pattern: your backend authenticates your user, then calls /v1/account/token to get a room token for them. A caller can only ever act as the member named in their token.

Tenant isolation#

Every room is owned by exactly one organization, bound on first use (first-wins). The rule, enforced on every room route and the WebSocket:

• When your backend mints a room token (/v1/account/token), the room is claimed for your org. Another org minting into the same room id gets 403 room belongs to another organization.
• Rooms created with no credential (the open demo path) are un-owned and reachable only by un-owned tokens — they are sealed off from org-owned rooms.
• Isolation is independent of the JWT signature: even a correctly-signed token with the wrong org claim is rejected.

Quickstart#

From zero to a delivered ciphertext in five calls. 1 and 2 are one-time setup; 3–5 are your per-user runtime.

curl -X POST __BASE__/v1/account/signup \
  -H "content-type: application/json" \
  -d '{"org_name":"Acme Capital","email":"[email protected]","password":"hunter2hunter2"}'
# → 201 {"token":"<dash-jwt>","org_id":"org_…","email":"[email protected]"}

curl -X POST __BASE__/v1/account/keys \
  -H "authorization: Bearer <dash-jwt>" \
  -H "content-type: application/json" -d '{"name":"production"}'
# → 201 {"key":"sk_live_…","key_id":"key_…","prefix":"sk_live_xxxxxxx"}

curl -X POST __BASE__/v1/account/token \
  -H "X-API-Key: sk_live_…" \
  -H "content-type: application/json" \
  -d '{"room":"deal-1","member":"alice","role":"principal"}'
# → 200 {"token":"<room-jwt>"}  (room "deal-1" is now owned by your org)

curl -X POST __BASE__/v1/rooms \
  -H "authorization: Bearer <room-jwt>" \
  -H "content-type: application/json" \
  -d '{"room_id":"deal-1","creator_id":"alice"}'

curl -X POST __BASE__/v1/rooms/deal-1/messages \
  -H "authorization: Bearer <room-jwt>" \
  -H "content-type: application/json" \
  -d '{"sender_id":"alice","kind":"application","epoch":1,"blob":"<base64-mls-ciphertext>"}'

Account API · sign up & log in#

{"token":"<dash-jwt>","org_id":"org_3f9a1c","email":"[email protected]"}

{"token":"<dash-jwt>","org_id":"org_3f9a1c","email":"[email protected]"}

{"user_id":"usr_…","email":"[email protected]","org_id":"org_…","org_name":"Acme Capital","plan":"free","role":"owner"}

Account API · API keys#

{"key":"sk_live_c48758…","key_id":"key_a1b2c3","name":"production","prefix":"sk_live_c48758","scopes":["token:mint"]}

{"keys":[{"key_id":"key_a1b2c3","name":"production","prefix":"sk_live_c48758","created_at":1718500000,"last_used":1718540000,"revoked":false}]}

Account API · mint a room token#

{"token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…"}

{"room":"deal-1","members":[{"member":"alice","role":"principal"},{"member":"bob"},{"member":"carol"}]}

{"tokens":[{"member":"alice","token":"…"},{"member":"bob","token":"…"},{"member":"carol","token":"…"}]}

Account API · webhooks#

Subscribe a URL to room events. Payloads are metadata only (never ciphertext) and HMAC-SHA256 signed with the endpoint secret. Events: message.created, member.joined, call.started, nda.accepted (empty events = all).

{"url":"https://api.acme.com/hooks/ollasync","events":["message.created"]}
→ {"id":"wh_…","url":"…","secret":"whsec_…","events":["message.created"],"created_at":…}

{"deliveries":[{"event":"message.created","code":200,"ok":true,"at":1718500000}]}

Event catalog: message.created · message.redacted · member.joined · member.removed · call.started · poll.closed · nda.accepted · recording.started · recording.completed · recording.failed.

Verifying a delivery

Each POST carries X-Ollasync-Event, X-Ollasync-Delivery (the webhook id), and X-Ollasync-Signature: sha256=<hex>. Recompute and compare:

sig = "sha256=" + hmac_sha256_hex(webhook_secret, raw_request_body)
verify_constant_time(sig, header["X-Ollasync-Signature"])

For backward compatibility the legacy X-SecureDeal-Event / -Delivery / -Signature headers are still sent alongside the X-Ollasync-* ones — prefer the new names.

{"event":"message.created","org":"org_…","room":"deal-1","ts":1718500000,
 "data":{"seq":42,"sender_id":"alice","kind":"application","epoch":1}}

Delivery is async with one retry. A durable redrive queue is a planned hardening.

Account API · team members#

An org owner/admin invites teammates by email + role (admin | dev). These are dashboard roles (who can manage the account) — not room roles.

Hardening

{"events":[{"actor":"usr_…","action":"key_create","target":"key_…","at":1718500000}]}

Login is brute-force-guarded: 5 failed attempts → a 5-minute lockout (429). Each API key tracks its lifetime requests + last_used (in the keys list).

Account API · usage & billing#

{"org_id":"org_…","usage":{"api_requests":1402,"tokens_minted":318}}

{"plan":"free","quota":100000,"used":318,"api_requests":1402}

Metering is metadata-only — request counts and token mints. The engine records no message content or participants.

Account API · password#

Account API · meetings#

Server-persisted meetings for the dashboard — a meeting is metadata over a call room, shared across your org's devices and admins. All routes are dashboard-session authed (a native dealroom dash token or a Better Auth JWT — see Identity).

{"id":"mtg_…","org_id":"org_…","title":"Board call","room":"mtg-…","start_at":0,"created_at":…}

{"token":"<room-jwt>","room":"mtg-…","member":"host","role":"principal"}

Recordings library

{"recordings":[{"id":"rec_…","room":"mtg-…","title":"Board call","status":"completed","started_at":…,"download_url":"https://…"}]}

Identity, orgs & SSO#

Production B2B identity is served by a dedicated Better Auth service at https://auth.ollasync.com — email/password, magic-link, social, passkeys, TOTP 2FA, organizations and per-org SSO. The dealroom trusts the identity it issues; the server-blind media plane never touches it.

The bridge — how the dealroom trusts identity

The dashboard plane (Account API, Meetings) accepts either a native dealroom dash token or a Better Auth JWT. The integration flow:

1. Sign the user in (any method below) → a session on auth.ollasync.com.
2. Get a short-lived EdDSA JWT: GET /api/auth/token.
3. Call the dealroom with Authorization: Bearer <that JWT>. The dealroom verifies it against the IdP's JWKS (GET /api/auth/jwks) and maps it to a dealroom org.

Sign in

Passkeys (WebAuthn)

Register and authenticate are two-step (options → browser WebAuthn → verify). rpID is the registrable parent so a passkey works across login. and auth.ollasync.com.

Also: GET /passkey/list-user-passkeys, POST /passkey/update-passkey, POST /passkey/delete-passkey.

Two-factor (TOTP)

Also: /two-factor/get-totp-uri, /two-factor/generate-backup-codes, /two-factor/verify-backup-code, /two-factor/send-otp, /two-factor/verify-otp.

Organizations & teams

Also: /organization/accept-invitation, /organization/list-members, /organization/remove-member, /organization/update, /organization/delete.

Single sign-on (OIDC & SAML)

Register an identity provider per organization; members whose email domain matches are routed to it at sign-in.

Also: GET /sso/providers, /sso/get-provider, /sso/update-provider, /sso/delete-provider, OIDC callback /sso/callback/{providerId}, and SAML 2.0 endpoints under /sso/saml2/….

This covers the identity endpoints Ollasync exposes. For the exhaustive Better Auth API and client SDKs, see better-auth.com/docs.

Rooms · create#

{"room_id":"deal-1","token":"<principal-room-jwt>"}

Rooms · key packages#

MLS key packages let a member be added to a group while offline. Each member publishes a pool; adding them consumes one (FIFO). Replenish when the count runs low.

{"member_id":"bob","count":7}

Rooms · members#

{"members":["alice","bob"]}

Rooms · invites & the join flow#

For self-serve joins (no server-minted token), a guest redeems an invite and the principal approves. The guest picks a private auth_nonce; the server never logs it, and only the holder of the nonce can later redeem the issued token.

{"token":"<invite>","expires_unix":0,"max_uses":0}

{"id":"req_…","member_id":"carol","display_name":"Carol","status":"pending","requested_at":1718500000}

{"token":"<room-jwt>","member_id":"carol","role":"member"}

Messages#

{"seq":42,"room_id":"deal-1","sender_id":"alice","kind":"application","epoch":1,"blob":"<base64>"}

[
  {"seq":41,"room_id":"deal-1","sender_id":"bob","kind":"commit","epoch":1,"blob":"…"},
  {"seq":42,"room_id":"deal-1","sender_id":"alice","kind":"application","epoch":1,"blob":"…"}
]

Reactions, threads & edits#

These sit beside the blind log: the server stores only the relations (and opaque edit ciphertext), never message meaning. All three also fan out over the WebSocket (reaction / edit events) and appear inline on message fetch (parent_seq, edited).

{"seq":42,"reactions":{"alice":"👍","bob":"🎉"},"counts":{"👍":1,"🎉":1}}

{"seq":42,"replies":[43,47,51]}

Pinned messages#

{"pins":[{"seq":42,"by":"alice","at":1718500000}]}

Polls#

A structured message. The server tallies votes by option index and never needs the text (send it opaque if you like). One vote per member (replaceable); multi allows several.

{"id":"poll_…","question":"Approve the deal?","options":["Yes","No","Abstain"],"multi":false,"closed":false}

{"id":"poll_…","options":["Yes","No","Abstain"],"counts":[5,2,1],"total":8,"your_vote":[0]}

Read-only / announcement rooms#

{"read_only":true,"auto_record":false,"message_ttl":86400}

Scheduled messages#

Hand the server an (already-encrypted) blob to release into the room at a future time. The server stays blind — it holds opaque ciphertext and appends it via the normal path at send_at.

Receipts & typing#

Presence#

Connecting the WebSocket also marks you online and emits presence to others automatically.

Realtime (WebSocket)#

{"type":"hello","online":["alice","bob"]}
{"type":"message","message":{"seq":43,"sender_id":"bob","kind":"application","epoch":1,"blob":"…"}}
{"type":"presence","member_id":"bob","state":"online"}
{"type":"typing","member_id":"bob","state":"start"}
{"type":"receipt","member_id":"bob","seq":43}
{"type":"call", "call":{ /* call signaling */ }}
{"type":"ping"}

const ws = new WebSocket(`${location.origin.replace('http','ws')}/v1/rooms/deal-1/connect?token=${roomJwt}`)
ws.onmessage = (e) => {
  const ev = JSON.parse(e.data)
  if (ev.type === 'message') decryptAndRender(ev.message)   // MLS decrypt client-side
  if (ev.type === 'ping')    ws.send(JSON.stringify({type:'pong'}))
}

Attachments#

Large files travel out-of-band via signed URLs; you encrypt the bytes client-side first. The capability is the signed URL, not the JWT.

{"attachment_id":"att_…","upload_url":"…","download_url":"…","expires_unix":1718600000,"max_size":26214400}

Deal-room · deals#

The workflow layer wraps a room with deal metadata, parties/roles, an NDA gate and a role-gated document vault. A deal is a room — every room route above also applies to a deal id.

{"deal_id":"deal-7a1c…","token":"<principal-room-jwt>","role":"admin"}

Deal-room · parties & roles#

{"parties":[{"id":"pty_…","org_name":"Buyer LLC","role":"buyer"}]}

Deal-room · NDA gating#

When an NDA is set, a member sees no documents until they accept it. Folder/document listings return nda_required: true (or 403 accept the NDA first) until then.

{"required":true,"text":"This Non-Disclosure Agreement…","accepted":false}

Deal-room · document vault#

Folders carry an access list of roles; documents inside are visible only to members whose deal-role is allowed (and who passed the NDA). Document bytes are E2E-encrypted client-side — the server stores ciphertext and serves signed URLs.

{"folders":[{"id":"fld_…","name":"Financials","access":["buyer","advisor"]}],"nda_required":false}

{"doc_id":"…","name":"P&L.pdf.enc","size":18234,"content_type":"application/octet-stream","uploaded_at":0,"upload_url":"…"}

{"download_url":"…","name":"P&L.pdf.enc","content_type":"application/octet-stream"}

Calls#

Voice/video runs over an SFU with E2EE media; the API issues per-room call tokens and relays ring/answer signaling. Media keys derive from the room's MLS exported secret — the SFU forwards encrypted frames only.

{"url":"wss://sfu…","token":"<livekit-jwt>","region":"eu","room":"call-deal-1"}

{"active":true,"call_id":"call_…","room":"deal-1","started_by":"alice","started_at":1718500000}

Signaling lifecycle, all room-token: POST …/call/{callId}/accept · /decline · /cancel · /leave · and principal-only /end.

{"calls":[{"id":"…","started_by":"alice","started_at":…,"ended_at":…,"participants":["alice","bob"]}]}

Region pinning: pass ?region=eu-de to call-token; set LIVEKIT_URL_<REGION> to route that region to a jurisdiction-specific SFU.

Retired webinar API

Webinar hosting, audience entry, stage controls and OBS publishing are permanently retired. Dedicated webinar endpoints return 404. Creating a meeting with webinar:true is rejected.

For older meeting clients only, authenticated GET /v1/rooms/{room}/webinar returns inactive state. It never creates media or issues a token. New clients should not call it. Historical records remain protected.

Recording#

Server-side recording via self-hosted LiveKit Egress → S3/MinIO (all open source, no paid services). The principal starts/stops; the backend tracks status and hands you a time-limited presigned download URL for the finished MP4.

{"id":"rec_…","room":"deal-1","egress_id":"EG_…","status":"active","file_key":"rec/call-deal-1-….mp4","started_by":"alice","started_at":…}

{"recordings":[{"id":"rec_…","status":"completed","file_key":"rec/…","download_url":"https://…?X-Amz-Signature=…"}]}

Options: recording/start accepts {audio:true} for audio-only (cheaper). Auto-record: PATCH …/settings {auto_record:true} starts a recording automatically when a meeting begins. Retention: set REC_RETENTION_DAYS to auto-delete old recordings.

Webhooks: recording.started / recording.completed / recording.failed. Deployment env: LIVEKIT_HTTP_URL, REC_S3_ENDPOINT, REC_S3_BUCKET, REC_S3_ACCESS_KEY, REC_S3_SECRET.

Moderation#

Principal escalation, all principal-only: POST …/moderation/{member}/suspend (mute — the member's sends return 403) · /unsuspend · /ban (blocks re-join). Full action history: GET /v1/rooms/{room}/audit.

Devices & push#

Idempotency#

Send an Idempotency-Key: <unique> header on create/mint POSTs to make retries safe — a repeat with the same key replays the original result (with Idempotent-Replay: true) instead of acting twice. Supported on:

• POST /v1/rooms · POST /v1/deals (creation)
• POST /v1/account/keys · POST /v1/account/token · /token/bulk
• POST /v1/rooms/{room}/messages (message send — see Messages)

OpenAPI spec#

curl __BASE__/v1/openapi.json | npx @openapitools/openapi-generator-cli generate -g typescript-fetch -i - -o ./sdk

Errors#

Errors are JSON: {"error":"human-readable message"} with a matching HTTP status.

Rate limits#

Per-IP token buckets, plus a per-identity ceiling across all authenticated routes. On exhaustion you get 429 with Retry-After: 1.

WebSocket connections are additionally capped per client IP.

Rate-limited responses carry X-RateLimit-Limit (the bucket's burst) and X-RateLimit-Remaining (tokens left); a 429 also sets Retry-After.

SDKs#

Typed clients are generated from this spec — TypeScript, Python, and Go, plus a Postman collection. Regenerate with sdk/generate.sh, or import /v1/openapi.json directly into Postman / Insomnia / your favourite generator.

// TypeScript (typescript-fetch)
import { Configuration, DefaultApi } from "./sdk/ts"
const api = new DefaultApi(new Configuration({ basePath: "__BASE__", accessToken: DASH_JWT }))

Voice messages need no special endpoint — send an audio file through attachments (content_type: audio/*) and reference it from a normal message.

Limitations & posture#

• "Blind" = blind to message body ciphertext. The server necessarily sees metadata — sender id, sequence, kind, room, timestamps — and routes on it.
• Recording disables E2E. Server-side recording requires the recorder to see decodable media; for a recorded session the SFU + egress handle plaintext. It's disclosed (a recording event + webhook), but it is a real relaxation. E2E-preserving recording would have to be client-side.
• Reactions and poll text are stored as the client sends them. The server tallies poll votes by index and treats emoji/option text as opaque, but if a client sends them in cleartext the server can see them. Encrypt them client-side if that matters.
• Single-node. One delivery service, one SFU, one egress node — so one recording at a time. No horizontal scaling yet.
• Ephemeral state (lost on restart): webhook delivery log, idempotency caches, login-lockout counters, rate-limiter, call-history dedup. Rooms, messages, accounts, keys, webhooks, deals, recordings metadata are Postgres-durable.
• Test deployment. Runs via go run with development secrets and self-signed certs. Not production-secured.

Building a client#

The server is transport. Your client owns the crypto. To interoperate, a client must:

• Run a conformant MLS (RFC 9420) stack — any library, any language. A common choice for web is Wire core-crypto (WASM); native clients can use any RFC-9420 implementation.
• Publish key packages so others can add you offline.
• Create/advance the MLS group locally; ship commit/welcome/proposal blobs as messages. Relay the commit to existing members (not just the welcome to the new one) or epochs desync.
• Encrypt application payloads and attachments to opaque blobs; the server stores them verbatim.
• Hold a WebSocket for delivery; fall back to GET …/messages?since= for catch-up.

← Back to the dashboard to create an API key and start minting tokens.