Architecture reference

Authentication & Authorization

Your app never handles passwords. Users prove who they are on secureFlows; your app only ever holds a short-lived session token.

This page explains how identity and access work end to end — hosted login, the session token, encrypted per-user storage, API calls, and logout — so you can evaluate the model with confidence before you integrate. For step-by-step HTTP details see the integration walkthrough and hosted login contract.

On this page
  1. Why this model is safe
  2. Authentication vs authorization
  3. Hosted login & redirect
  4. Login
  5. Session token & storage
  6. Session data operations
  7. Logout
  8. The entire flow

Why this model is safe

Most breaches in client apps start with credentials or tokens living in the wrong place: a password form you built yourself, a token in localStorage, or identity taken from a request body the client can forge. secureFlows is designed so those paths are not part of a correct integration.

No credentials in your app

End users sign in on secureFlows hosted login. Your product never sees email/password or provider secrets — only a sessionToken after a successful redirect.

Identity comes from the token

Workspace, user, and app binding are taken from the verified session JWT on the server. Clients must not send “who I am” in JSON bodies for Session API calls.

Data stays when tokens expire

Token lifetime and data lifetime are separate. The default is durable user data; a 410 on an expired token means “sign in again,” not “your data was deleted.”

Encrypted at rest, isolated per tenant

Session payloads are encrypted before storage. Workspaces are hard isolation boundaries — another tenant cannot read your ciphertext even with raw database access.

Authentication vs authorization

Concept What it answers In secureFlows
Authentication Who is this person? Firebase Auth on the hosted login page proves identity. secureFlows then mints a session token bound to that user, workspace, and application.
Authorization What may they do now? Every Session API request presents Authorization: Bearer <sessionToken>. The API loads the session from that token and allows only that user’s encrypted record — no cross-user access by construction.
Admin / console Who may manage the workspace? Separate from end-user sessions: owners and admins use Management API user JWTs after console sign-in. End-user apps stay on the Session API path.

Hosted login & redirect

Hosted login is the browser page on secureFlows where your user authenticates. Your app sends them there with query parameters that name the workspace, application, and an allowlisted return URL. After success, secureFlows redirects back to your app with a sessionToken (and optional state for CSRF binding).

Hosted login redirect between your app and secureFlows Your app redirects the browser to secureFlows hosted login; after sign-in secureFlows redirects back to your allowlisted callback with a sessionToken. Your application Browser app Opens hosted login Receives sessionToken secureFlows /app/sessions/login Firebase sign-in Mint session + redirect Your callback /callback ?sessionToken=… &state=… 1. Redirect 2. Return redirect_uri must be exactly allowlisted on the application (including path).
Credentials stay on secureFlows. Your app only participates as the start and end of a browser redirect.

Required query parameters

Parameter Purpose
workspace_name Which tenant this login belongs to.
app_id Which registered application is logging the user in (scopes redirect allowlist and session).
redirect_uri Exact callback URL on your origin (typically https://<your-host>/callback). Must match the application allowlist.
state Opaque value you generate; returned unchanged so you can bind the round-trip (CSRF defense).
Use /app/sessions/login for session apps

/app/login is for console sign-in and a legacy Firebase-token path — not the session-token integration contract. Session products should always use hosted session login.

Login

On the hosted page the user signs in with Firebase (email/password or configured providers). secureFlows never silently auto-completes a redirect just because another tab was signed in: if a prior identity is restored for this application’s Firebase instance, the user must confirm with an explicit “Continue as …?” step (or choose a different account).

Login steps on hosted session login User lands on hosted login, authenticates with Firebase, secureFlows validates the redirect URI, creates or reuses a session, then redirects to the app callback. Land on hosted login Sign in Firebase Auth Confirm if identity restored Validate redirect allowlist Mint session Then 302 → your redirect_uri with sessionToken (+ state). App stores token and continues.
Repeated sign-ins for the same user and app reuse an active session when appropriate — they do not invent a new identity on every click.

Session token & storage

The sessionToken is a signed JWT that authorizes Session API access for one user in one workspace for one application. Treat it like a browser session credential:

Where the session token lives Callback stores the session token in sessionStorage; subsequent API calls send it as a Bearer header to the Session API. /callback Read sessionToken from query string sessionStorage per tab / window keyed by workspace + appId Session API Authorization: Bearer … identity from token only Closing the tab clears sessionStorage. That ends the browser session — not the durable user record.
Tab-scoped storage reduces long-lived token theft compared with localStorage, while the vaulted user data continues to live on the server.

Session data operations

With a valid bearer token, your app reads and writes the user’s encrypted JSON record through the Session API. Typical operations:

Authorized session data access The app sends the session token; the API verifies it, loads the matching session, encrypts or decrypts the payload, and returns only that user's data. Your app Bearer sessionToken set / get / delete secureFlows Session API 1. Verify JWT & revision 2. Resolve user session 3. Encrypt / decrypt payload Encrypted store Per-user record Workspace isolated 401 / 410 / signed-out 403 → clear token and send the user through hosted login again. Data is still there.
Authorization is implicit in the token: there is no client-supplied user id to spoof on Session API writes.

Logout

Signing out is a first-party redirect through secureFlows so the session token is invalidated in a controlled way (and hosted-login cookies can be cleared). Browser apps should use the hosted logout redirect — not only delete a key from sessionStorage.

Logout redirect flow App navigates to secureFlows logout with the session token; secureFlows revokes the session and redirects back to the app home, which then shows sign-in again. Sign out Keep token until navigation starts GET /api/v1/auth/logout Revoke session token Clear hosted auth state Back to your app redirect_uri = / Show login / CTA Logout redirect_uri is your app home (/), not /callback. Do not pass a dead session_token on the next login.
After logout, the next screen must be login or a Continue CTA — never the main UI calling the Session API without a bearer token.

The entire flow

Putting it together: provision an application once in the console, then every end-user trip is hosted login → token in sessionStorage → Session API → optional logout. Your code never becomes a password store or an identity authority.

End-to-end authentication and authorization flow Vertical swimlane of the full user journey from sign-in CTA through hosted login, callback, API usage, and logout. Your app secureFlows User / browser 1. Continue / Sign in CTA No token yet Browser navigates to hosted login 2. Hosted login Authenticate + mint session 3. /callback Store token · leave /callback 4. Session API calls Bearer on every request Authorize + read/write Encrypted per-user data 5. Sign out Logout redirect Revoke session Redirect to app home 6. Signed-out UI / CTA
One redirect loop for sign-in, one for sign-out, and a bearer token for everything in between.
What not to build

Do not collect passwords in your UI, store session tokens in localStorage, trust a user id from the client body, decode the JWT for “who am I,” or treat HTTP 410 as data loss. Those patterns undo the safety guarantees above.

Related reading: End-to-end user management, Security infrastructure, System components, Session API.

Your app ships features. secureFlows holds identity and the vault.