Auth - Cognita

Cognita supports two authentication methods:

OAuth2 Authorization Code (enterprise SSO) — for organizations integrating with SSO (Google/Microsoft/SAML). Use standard token endpoint and consent flows.

JWT Bearer Tokens — short-lived access tokens (recommended TTL: 15m) and refresh tokens for clients.

Service tokens — long-lived tokens for server-to-server communication (scoped & rotate).

mTLS — optional for internal service communication.

Webhook signing — HMAC SHA256 signature using X-Cognita-Signature header.

Bearer Header Example:

Authorization: Bearer eyJhbGciOiJ...

OAuth scopes Example

meeting:read, meeting:write, transcript:read, transcript:write, summaries:read, integration:jira:write, org:admin

Quick reference

Purpose	Method	Path	Auth
Register	POST	`/register`	none
Verify email	POST	`/verify-email`	none
Login (password)	POST	`/login`	none
Refresh token	POST	`/refresh`	none (send refresh token)
Logout	POST	`/logout`	Bearer
Forgot password	POST	`/forgot-password`	none
Reset password	POST	`/reset-password`	none
MFA setup	POST	`/mfa/setup`	Bearer
MFA verify	POST	`/mfa/verify`	depends on flow
Get current user	GET	`/me`	Bearer
Update profile	PUT	`/me`	Bearer

Important HTTP codes

200 OK — successful GET/PUT/POST (non-create).
201 Created — resource created (e.g., register).
202 Accepted — async or MFA required.
400 Bad Request / ValidationError
401 Unauthorized — invalid/expired access token
403 Forbidden — e.g., TokenCompromised or insufficient scope
404 Not Found
409 Conflict — duplicate entity (email exists)
429 Too Many Requests — use Retry-After header
500 Internal Server Error

Token storage & security best practices (for consumers)

Web (SPA)

Preferred: store refreshToken in HttpOnly Secure cookie (same-site=Strict or Lax per UX). Keep accessToken in memory, or short-lived in memory + refresh cycle.

Avoid storing tokens in localStorage (XSS risk).

Native mobile

Store tokens in device’s secure store (Keychain / Keystore). Use rotation.

Server-to-server

Keep keys and refresh tokens in secure vault (env vars for short-term only, or a secret manager). Use client credentials for backend integrations.

Always

Send tokens only over HTTPS.

Implement CSRF protections such as double submit cookies or same-site.

Validate server expiresIn and schedule refresh proactively (e.g., at 70-80% expiry).

On 401 -> attempt refresh once, then redirect to login if refresh fails.

Retry/backoff rules for clients

On 429 use Retry-After header value (server-provided).

On 500/502/503 use exponential backoff with jitter, max retries = 3.

For idempotent GETs, safe to retry. For POSTs, use Idempotency-Key (server will dedupe).

Authentication

Bearer Header Example:#

OAuth scopes Example#

Quick reference#

Important HTTP codes#

Token storage & security best practices (for consumers)#

Web (SPA)#

Native mobile#

Server-to-server#

Always#

Retry/backoff rules for clients#