The API supports several authentication modes. Each is appropriate for different callers — interactive users, server-to-server, mobile apps.
Cookie / Session
When a user signs in via the web UI, a session cookie is set. The same cookie authenticates API calls from the browser. This is the default mode for browser-based traffic.
Bearer User Token
Mobile apps or single-page applications obtain a JWT from POST /auth/login and present it as Authorization: Bearer …. Tokens are short-lived (1 hour); refresh tokens last 30 days.
API Key
For service-to-service calls (no human in the loop). See the “Authenticating with API Keys” article.
OAuth 2.0 / OpenID Connect
For third-party integrations where users grant access to your platform on behalf of another service. Standard OAuth flows are supported.
mTLS
For very high security (banking, government), enable mutual TLS — both server and client present certificates. Configure trusted CAs and require client certificate verification at the reverse proxy.
Worked Examples
- Browser SPA: Session cookie for the web app; same cookie used for fetch() calls.
- iOS app: Bearer token, refresh on 401, sign in via the OS keychain-backed refresh token.
- CRM integration: Service API key, scope read+write on customers and orders.
- Customer-facing OAuth: Customer can authorise their Slack to receive notifications; standard OAuth flow grants the platform a Slack token while granting Slack scoped access back.
- Government tenant: mTLS for all admin API endpoints; client cert held in the tenant's HSM.
Note: Mix modes as you need to. The same endpoint will accept any valid authentication; the platform identifies the caller and applies the corresponding permission set.