Governance evidence

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:

1. The permission audit log — queryable in PostgreSQL.
2. The write path — what CYPEX captures automatically, and what it does not.
3. 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.

Permission decisions are queryable directly in PostgreSQL, in cypex_log.t_permission_audit_log. Use it to answer “why was this user allowed or denied on this row?”

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

-- The 50 most recent access decisions, newest first
SELECT created_at, action, entity_type, entity_name, user_id, user_name, organization_id
FROM   cypex_log.t_permission_audit_log
ORDER  BY created_at DESC
LIMIT  50;

-- Only the refusals
SELECT created_at, entity_type, entity_name, user_name, context
FROM   cypex_log.t_permission_audit_log
WHERE  action = 'ACCESS_DENIED'
ORDER  BY created_at DESC;

The table is protected by row-level security. A system admin sees every row. An organization admin sees rows for the organizations they are mapped to, and also every row whose organization_id is NULL.

Warning

The permission audit log is deployment-wide evidence, not per-tenant evidence. Only connector-execution rows carry an organization_id; every other kind of row leaves it NULL, and NULL rows are visible to every organization admin. Do not rely on this table to keep one tenant’s decisions hidden from another tenant’s administrator, and do not assume that filtering on organization_id returns a complete picture for that organization.

Access-control decisions are recorded in cypex_log.t_permission_audit_log. The audit row carries:

Both action and entity_type are plain text columns with no database constraint, so a value you have not seen before is possible after an upgrade.

When an audit row is written while handling a request, that request’s correlation id is stamped into context ->> 'correlationId' automatically. The id comes from the inbound x-request-id header when the caller supplies a well-formed one, and is generated otherwise. Rows written outside a request — platform-initiated actions such as connector runtime credential access — have no correlation id, and context may be NULL. Join on context ->> 'correlationId' to reconstruct everything a single request touched.

Creating, updating or deleting an Organization, and mapping roles to it, is recorded in cypex_log.t_log_api. It does not appear in t_permission_audit_log at all, so “who created this organization?” and “when was this role granted?” must be answered here:

1
2
3
4

SELECT ts, event, description, user_id, payload
FROM   cypex_log.t_log_api
WHERE  event LIKE 'organization.%'
ORDER  BY ts DESC;

The payload column carries the organization id, name and domain. t_log_api also has an organization_id column, but nothing populates it — filter on event and payload, not on that column.

Successful decisions are recorded as well as refusals, so an empty result for a user is meaningful: it means no decision was ever evaluated, not that access was granted silently.

Connector executions are the one domain with a dedicated admin screen. Open Connector Audit under Monitor & Audit in the sidebar — it is reserved for system admins — instead of querying the table by hand.

Some evidence lives outside the database, in product documentation and release artifacts:

The three migrations run automatically as part of the upgrade. To confirm they took effect on a given deployment:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

-- Default Organization was seeded
SELECT id, name, organization_domain FROM cypex.t_organization;

-- RLS helper functions are present
SELECT proname FROM pg_proc p JOIN pg_namespace n ON n.oid = p.pronamespace
WHERE  n.nspname = 'cypex'
AND    proname IN ('is_admin', 'is_organization_admin',
                   'current_organization_id', 'current_user_organization_ids');

-- Row-level security is enabled on the tenant-scoped tables
SELECT schemaname, tablename, rowsecurity FROM pg_tables
WHERE  schemaname IN ('cypex', 'cypex_log') AND rowsecurity
ORDER  BY tablename;

Tip

When you make a non-trivial decision about an Organization, leave evidence in at least two of the three layers:

1. Run the relevant query on cypex_log.t_permission_audit_log and, for organization management, on cypex_log.t_log_api, and keep the output with the change record.
2. Add an ADR-style note under CYPEX internals describing the decision, the alternatives considered, and the rollback plan.
3. If the decision changes the migration sequence or the tenancy contract, update the relevant page in this section and the v2.0.0 release notes.

• SSO — Pending and rejected users — this same evidence model applied to SSO approve/reject/un-reject decisions.
• What is an Organization? — the tenancy contract.
• Connector Audit — the admin screen for connector execution evidence.
• Upgrade to CYPEX v2.0.0 — the mandatory operator upgrade entry point, including post-upgrade verification queries.
• CYPEX internals — where new ADR-style evidence should live.
• Release Notes v2.0.0 — the release entry that introduces multi-tenancy.