secureflows-mcp

Browser redirect endpoint used after hosted /app/sessions/login. No Authorization header.

1. Verifies firebaseToken (Firebase ID token).

2. Ensures client_redirect_uri is allowlisted for app_id (same rules as validate-redirect).

3. Create vs renew: If session_token is absent, reuses the newest active session for (workspace_name, Firebase UID, app_id) or creates one (get-or-create). Optional payload (URL-encoded JSON object, default {}) is stored only on create — ignored when reusing an existing session. If session_token is present (previous session JWT, may be expired), renews that session; payload must not be sent on the same request. Optional ttl_seconds applies to both paths (default 0 = unlimited; otherwise 60–604800). When the Firebase token includes email, the server best-effort persists or backfills it on the workspace end-user row (audit display only).

4. Responds with 302 Found to client_redirect_uri with query params sessionToken and, if provided, state.

If client_redirect_uri is not allowed for app_id, responds 400 and does not redirect (open-redirect mitigation). Other failures return an HTTP error status with a JSON {"status", "error"} body and do not redirect.

Source: GET /api/v1/auth/callback No Authorization header is required. Prefer connection.workspaceName and connection.appId as stable config instead of generating identity fields dynamically.

Removes key from the session payload and returns true if the key existed.

Source: DELETE /api/v1/sessions/delete/{key} Requires auth.sessionToken and forwards it as a Bearer token. Prefer connection.workspaceName and connection.appId as stable config instead of generating identity fields dynamically.

Browser-friendly logout endpoint for cross-site clients (e.g. apps running on localhost).

Use this as a top-level navigation (not XHR/fetch) so Clear-Site-Data is applied in a first-party context on secure-flows.com, making cookie/session clearing reliable even when third-party cookies are blocked.

Critical client rules:

• Clear your in-app sessionToken state before navigating.

• Never include session_token inside redirect_uri (that would silently renew and defeat logout).

This endpoint (best-effort / idempotent for browser UX):

• Invalidates the provided session_token by incrementing tokenRevision when the token still matches an active session (no new token is issued).

• If the session is already expired/revoked or the revision was superseded by renew, still completes logout UX (does not return 401 solely for that reason).

• Revokes Firebase refresh tokens for the session’s stored Firebase UID when known.

• Sets Clear-Site-Data: "cookies".

• Redirects the browser to redirect_uri.

Source: GET /api/v1/auth/logout No Authorization header is required. Prefer connection.workspaceName and connection.appId as stable config instead of generating identity fields dynamically.

Embeds the query with Ollama (nomic-embed-text) and returns the closest public doc chunks from the environment's search index (pgvector).

Source: GET /api/v1/docs/search No Authorization header is required. Prefer connection.workspaceName and connection.appId as stable config instead of generating identity fields dynamically.

Returns the decrypted session payload for the authenticated internal session token.

Response shape is a flat JSON object. Empty payload returns {}.

Source: GET /api/v1/sessions Requires auth.sessionToken and forwards it as a Bearer token. Prefer connection.workspaceName and connection.appId as stable config instead of generating identity fields dynamically.

Retrieves the decrypted payload value for key.

Important: 404 means the key was never written (normal first-use case). Do not treat as an error.

Source: GET /api/v1/sessions/get/{key} Requires auth.sessionToken and forwards it as a Bearer token. Prefer connection.workspaceName and connection.appId as stable config instead of generating identity fields dynamically.

Returns the workspace end-user's userId and email for the authenticated session token. Does not return Firebase UID or session payload.

userId is a stable, opaque identifier for this person across sessions and logins — it is not derived from Firebase. Use it as the correlation key when your own backend needs to link an external event (e.g. a billing provider webhook you receive and verify yourself) back to this user. Do not use the session token or session id for this — sessions expire and rotate, userId does not.

Email is best-effort from hosted login (Firebase email claim persisted on the user row). When unknown, email is null. Browser SDK: secureflows-js fetchSessionIdentity(token) (≥ 0.1.15 for userId).

Source: GET /api/v1/sessions/identity Requires auth.sessionToken and forwards it as a Bearer token. Prefer connection.workspaceName and connection.appId as stable config instead of generating identity fields dynamically.

Returns a page of sessions for the current user within the current workspace. Self-service dashboard endpoint — requires workspace enableSelfService: true. Payload is included only for rows whose computed status is active. Sort keys match the admin workspace session list; pageSize is clamped to 1–200 (default 20).

Source: GET /api/v1/sessions/my Requires auth.userToken and forwards it as a Bearer token. Prefer connection.workspaceName and connection.appId as stable config instead of generating identity fields dynamically.

Logs out the current session without revoking it.

Browser warning: calling this endpoint via XHR/fetch from a different origin than secure-flows.com is not a reliable way to clear hosted-login cookies. For browser apps (especially localhost), prefer the redirect helper GET /api/v1/auth/logout?session_token=...&redirect_uri=....

Behavior:

• Invalidates the current sessionToken by incrementing tokenRevision (no new token is issued).

• Calls Firebase revokeRefreshTokens(firebaseUid) using the session’s stored Firebase UID.

• Sets Clear-Site-Data: "cookies" to clear browser cookies (including Firebase session cookie).

Session payload and session row are not deleted or modified (other than tokenRevision).

Source: POST /api/v1/auth/logout Requires auth.sessionToken and forwards it as a Bearer token. Prefer connection.workspaceName and connection.appId as stable config instead of generating identity fields dynamically.

Verifies Firebase ID token, creates a session for workspaceName, stores serialized payload (defaults to {} when omitted), and returns sessionToken (JWT; subject = internal session id). Default server-side TTL is 1 hour (implementation detail).

If the Firebase token includes email, the server best-effort persists it on the workspace end-user row (for audit display). Prefer POST /sessions/get-or-create for hosted-login-style flows that should reuse an active session.

Source: POST /api/v1/sessions Requires auth.firebaseToken and forwards it as a Bearer token. Prefer connection.workspaceName and connection.appId as stable config instead of generating identity fields dynamically.

Verifies Firebase ID token. If an active session already exists for (workspaceName, Firebase UID, app_id), returns a new sessionToken JWT for the most recently created matching row (touches activity; does not create a duplicate session). The request payload is ignored on reuse — it is applied only when a new session row is created. Prefer a dedicated app_id per integration surface, or revoke old sessions, if you need a fresh payload.

Otherwise behaves like POST /sessions (new row + default 1 hour TTL).

If the Firebase token includes email, the server best-effort persists or backfills it on the workspace end-user row (including when reusing an existing session). Intended for integrators that mirror hosted login session reuse.

Source: POST /api/v1/sessions/get-or-create Requires auth.firebaseToken and forwards it as a Bearer token. Prefer connection.workspaceName and connection.appId as stable config instead of generating identity fields dynamically.

Verifies Firebase ID token. Parses sessionToken path segment as an internal SESSION JWT without enforcing JWT expiry (signature and tokenType=SESSION are still validated). Loads the session by id from the token subject; the Firebase UID must match the session owner. Increments tokenRevision on the server so previous session JWTs (same session id, older revision) are no longer accepted for GET/POST/DELETE /sessions/.... Returns a new sessionToken (with the new tokenRevision claim) and the current decrypted payload; extends server-side session expiry by 1 hour.

If the Firebase token includes email, the server best-effort backfills it on the session owner when the user row has no email yet (audit display only).

Use the path form POST /api/v1/sessions/renew/{sessionToken} — URL-encode the JWT (e.g. encodeURIComponent in JS).

Source: POST /api/v1/sessions/renew/{sessionToken} Requires auth.firebaseToken and forwards it as a Bearer token. Prefer connection.workspaceName and connection.appId as stable config instead of generating identity fields dynamically.

Permanently revokes the session referenced by the internal SESSION Bearer token. The session ends and everything stored in it is destroyed and cannot be restored. This is NOT sign-out: to sign a user out and keep their data, use POST /api/v1/auth/logout (or, in a browser, the redirect helper GET /api/v1/auth/logout). Call revoke only when the user or an admin deliberately wants the session and its data deleted, for example on account deletion.

Source: POST /api/v1/sessions/revoke Requires auth.sessionToken and forwards it as a Bearer token. Prefer connection.workspaceName and connection.appId as stable config instead of generating identity fields dynamically.

Self-service dashboard endpoint. Revokes a session owned by the caller in the current workspace. The session ends and its stored data is destroyed permanently; this is not sign-out. Requires workspace enableSelfService: true.

Source: POST /api/v1/sessions/revoke/{sessionId} Requires auth.userToken and forwards it as a Bearer token. Prefer connection.workspaceName and connection.appId as stable config instead of generating identity fields dynamically.

Sets a key in the encrypted session payload and returns the updated decrypted payload. If the JSON body is { "value": <x> }, the server unwraps it and stores <x> directly.

Source: POST /api/v1/sessions/set/{key} Requires auth.sessionToken and forwards it as a Bearer token. Prefer connection.workspaceName and connection.appId as stable config instead of generating identity fields dynamically.

Builds a correct hosted-login redirect URL. Needs no secureFlows token — safe to call at app-scaffolding time, before any user session exists, which is the phase most secureFlows integration mistakes happen in.

Always targets /app/sessions/login (session apps). Never builds the legacy /app/login console URL, which returns a firebaseToken your SecureFlowsCallback handler cannot consume and causes an infinite redirect loop.

Use this instead of hand-building the URL with URLSearchParams — hand-built login URLs are the #1 source of the login-loop and stale-renewal bugs documented in SKILL.md.

Builds a correct redirect-logout URL and refuses to build one that violates the two documented logout anti-patterns: a redirect_uri pointing at /callback (SPA callback handlers treat the tokenless return as a failed login and loop), and a redirect_uri that itself embeds session_token (silently renews the old session instead of signing out).

The result always instructs top-level navigation, never fetch/XHR — cross-site fetch() to this endpoint gets a 200 but browsers silently ignore its Clear-Site-Data header on cross-site responses, so the hosted-login cookie survives and the user silently re-authenticates on the next login redirect. This tool never builds a revoke request: revoke permanently destroys the user's data and must only run on an explicit "delete my account" action, never on ordinary sign-out.

Checks source you already generated against the secureFlows integration rules. Needs no secureFlows token; safe at scaffolding time. Pass every auth/session-related file in one call — some checks are evaluated across the whole set.

Two kinds of findings: • scope "file" — a forbidden construct is present (localStorage token, legacy /app/login, fetch-based logout, client-side JWT decode, empty catch, restore non-auth errors clearing session UI, Continue CTA gated on null session, ...), reported at an exact file:line. • scope "project" — REQUIRED handling is missing everywhere you passed in: detecting 401/410 but never clearing the token, never handling 403, or handling 403 without the BILLING_GRACE_LOCK carve-out. These are the defects that actually dominate real generated apps, and no "forbidden pattern" check can see them, because the bug is an absence.

Heuristic text analysis, not a parser or a type checker. It can miss things it has no rule for, and a project check can be satisfied by the right keyword in the wrong place. It is a fast first pass — not a substitute for the Agent implementation checklist in SKILL.md, and specifically not for the checks that need a running app (auth-guard mount races, the fresh-reload check). Fix every "error" before calling an integration done; treat "needs_review" as a lead.