Session flow (interactive)
1
POST /api/v1/auth/session
With
{ email, password } body. If 2FA is enabled (it is, for all PHI accounts), the server responds with a 402 Two-Factor Required including a short-lived continuation token.2
POST /api/v1/auth/session/2fa
With
{ continuation_token, code } or the passkey assertion. On success, the server sets an httpOnly session cookie.3
Subsequent requests
Include the cookie automatically. Browser requests need no additional headers.
4
POST /api/v1/auth/session/logout
Server revokes the session and clears the cookie.
Example
CSRF protection
Because authentication is cookie-based, state-changing requests require a CSRF token:- The server sets a
csrf_tokenvalue in a readable cookie on login. - Clients send this value as
X-CSRF-Tokenon everyPOST,PUT,PATCH,DELETE. - Safe methods (
GET,HEAD,OPTIONS) don’t need the token.
Other factors
Passkeys (WebAuthn)
For passkey sign-in, the 2FA step is replaced by a WebAuthn assertion. See the full flow in the API reference.
Magic links
POST /api/v1/auth/magic_link sends a one-time sign-in link. Link includes a short-TTL token that, when consumed, establishes the session.Google OAuth 2.1
GET /api/v1/auth/oauth/google redirects to Google; return callback establishes the session.SAML SSO
Enterprise SAML 2.0 via
POST /api/v1/auth/saml/<provider>. See SSO / SAML.API tokens (server-to-server)
For non-browser use cases (EHR webhooks, server-side integrations), request a scoped API token:1
Generate a token
Settings → Developers → API tokens → New token. Choose scopes (
documents:write, denials:read, etc.) and an expiry.2
Use the token
dbs_live_ or dbs_test_) and a checksum suffix.3
Rotate
Regenerate from the same settings page. Old tokens remain valid for a configurable grace window.