Clerk Runbook: Organizations, SSO & RBAC

Praxion uses Clerk for authentication and organization management. Each Clerk Organization maps 1:1 to a Praxion workspace — there is no shared "default workspace", so billing, glossary and audit logs are always scoped to a single org. This runbook covers the mapping, the role model, SSO, and the operations you will actually run.

The org → workspace mapping

When a Clerk Organization is created, Praxion provisions a matching workspace and binds it via the org ID. All of the following inherit that scope automatically:

• Optimizer suggestions, the schema map and the glossary
• Natural-language query sessions and the terms they resolve against
• CI gate keys and the verdicts they produced
• Audit log (hash-chained, append-only)
• Billing — the workspace is the billing unit

Roles and RBAC

Identity-provider groups are mapped to local roles through the role_mappings table. The local role set is viewer, optimizer, admin, auditor, billing and agent. Three of them cover the everyday cases:

auditor and billing complete the set so that reading the audit chain or the invoice does not have to mean handing out admin. agent is not a person at all — it is the credential type an agent presents when it reports.

role_mappings is deployment-wide rather than per workspace, which is why it is managed by Praxion support instead of from the dashboard: the API behind it requires an operator key, not an admin session. Send your IdP group names and the roles you want them to land on.

Enabling SSO

Enterprise SSO is available on the Enterprise plan and billed per connection, and it is not self-serve: the settings screen shows it as not purchased until it has been enabled for your workspace.

1. Ask your account manager to enable SAML. Okta and Azure AD are the providers we support.
2. We create the connection; you require SSO for the org if your policy demands it.
3. Test with a burner account before rolling out to everyone.

Once SSO is active, group membership in your IdP drives roles through the mapping table — a clerk group org:admin lands on admin, and org:member lands on viewer.

Common operations

Add a member

Invite colleagues from the Team screen. Invitations are sent by email and expire. A colleague who accepts joins the same organization and shares its glossary, its database connections and its invoice — as a member, which maps to the viewer role. They can read the dashboard but cannot connect databases or change billing. Promote them to admin from the members tab if they need to.

Remove a member

Removing someone from the Clerk org revokes their workspace access instantly. Their sessions are invalidated on the next request; audit log entries are not deleted — ever.

Rotate a CI key

The key lives on the CI Gate screen, beside the pipeline it belongs to. Create the replacement there, update the secret in GitHub or GitLab, and revoke the old one. Do this whenever someone with access to your CI secrets leaves.

Troubleshooting

• User cannot see the workspace. Check they are in the org and that a mapping gives them at least viewer. The usual cause is the bootstrap row having been removed before their IdP group was mapped, which leaves them with no role at all.
• SSO login loops. Confirm the SAML connection points at the same org ID as the workspace, then retry in an incognito window.
• Role feels wrong. Verify the IdP group mapping — the role comes from the mapping table, not from the IdP role name.
• Billing shows the wrong org. Billing is bound to the workspace. Check which organization owns the workspace before questioning the invoice.