Every SSO identity CYPEX has ever seen sits in sso_gateway.t_sso_user_map in exactly one of three states (sso_gateway.user_map_status): pending, active, or rejected. This page documents the full lifecycle — what moves a row between states, what each transition writes to the audit trail, and where to find evidence of a governance decision. For adding a provider and the first successful sign-in, see the OIDC setup guide.
States
State
Meaning
What a repeat login does
Pending
IdP authentication succeeded, but no t_sso_role_mapping rule matched and (if Auto-link by email is off, the default) no admin has reviewed it yet. cypex_user_id and cypex_role are both NULL.
Refreshes the captured profile in place, stays pending. The exchange returns 403 pending_approval — “Your account is pending administrator approval.”
Active
An admin approved or linked the identity, or a role mapping matched automatically. cypex_user_id and cypex_role are set.
Signs in normally; mints an access/refresh token pair like any other login.
Rejected
An admin explicitly rejected the identity. The row is kept (not deleted) — rejected_at, rejected_by, and an optional rejection_reason (≤200 characters) are recorded.
Blocked. The exchange returns 403 user_rejected — a deliberately generic “This SSO identity has been blocked. Contact your administrator.” The real reason and who rejected it never reach the browser; they’re in the audit trail only.
Users → Pending SSO and Users → Rejected SSO are the two admin-facing queues for the states above:
Every save in the Application Designer creates a save point — a recoverable
prior state of the application. v2.0.0 makes saving cheaper to do and easier to
read back.
Quick save — Ctrl+S
Press Ctrl+S (Cmd+S on macOS) anywhere in the editor to save
immediately. No dialog opens. A Saved confirmation appears when it
succeeds; if it fails, the error appears in its place.
After running the client-assignment migration,
walk through the verification queries on this page. If verification
fails, follow the rollback procedure.
This page is for people who build and ship CYPEX applications. It covers what
changes about that job once a deployment has more than one Organization.
Organization scope on this page is enforced by CYPEX itself, not by the browser.
Hiding a row in the admin panel would be cosmetic; what is described below holds
even for a caller who manipulates the request directly.
Application visibility per organization
The Applications page does
not show every application in the deployment to every admin. A system admin can
pick any organization in the organization filter, or clear it to see everything.
An organization admin is always restricted to their own organization — changing
the filter in the browser does not widen what comes back.
CYPEX federates login to an external identity provider in two ways. OIDC and OAuth2 logins go through a standalone SSO Gateway service; LDAP is handled inside CYPEX itself and does not involve the gateway. Both paths end the same way: a successful federated login issues a PostgREST-compatible JWT, and the organization and role claims on that token drive the same PostgreSQL Row-Level Security (RLS) policies as local username/password auth. There is no separate SSO security path.
This is the conceptual / architecture reference. For the hands-on, step-by-step walkthrough with screenshots and a real sanitised request/response, see the Setup guide. For the admin-panel GUI reference (screenshots, field-by-field), see Connectors, Connector Secrets, Connector Allowlist, and Connector Enablement.
Pages in this section
This page — the conceptual / architecture reference.
Setup guide — the hands-on E2E walkthrough: rollout, allowlist, credentials, the guided builder, publish, execute, and audit.
A Connector is a governed, server-side definition for calling a third-party REST API and mapping its response into a typed shape a CYPEX application can render — an authenticated CYPEX user’s page can show a table backed by a live external API call, next to tables backed by CYPEX’s own PostgreSQL data.
A change that affects a tenant boundary should be reconstructable afterwards.
CYPEX records part of that automatically and leaves the rest to you. This page
documents the three layers where evidence lives, in order of increasing
persistence:
The permission audit log — queryable in PostgreSQL.
The write path — what CYPEX captures automatically, and what it does not.
Documentation approvals — recorded in product docs and release notes.
If you make a non-trivial decision about an Organization (split, merge, role
remap, schema revoke), keep the audit query and its output with the change
record, and add an ADR-style note under
CYPEX internals.
This page lists the upgrade scenarios that were exercised against the v2.0.0
migration scripts, the result of each, and the explicit answer to the most
common question: does RLS change row visibility for existing single-tenant
data?
Short answer
Info
No. RLS does not change row visibility for existing single-tenant data.
All existing rows remain visible to all existing users after the upgrade.
The mechanism is described in detail on
RLS impact on existing data. The short
version: the upgrade creates a Default Organization, maps every existing
role to it, and the RLS policies explicitly allow organization_id IS NULL
rows to be visible. Existing single-tenant data therefore continues to be
readable.
This page answers the most common question about the v2.0.0 upgrade:
Info
Does enabling RLS change row visibility for existing single-tenant data?
Short answer
No. Existing single-tenant data remains visible to all existing users
after the upgrade. The migration is designed so that the transition from
v1.x to v2.0.0 is transparent for end users at the row-visibility level.
