WorkOS AuthKit: how do we enable organizations, RBAC, and org-level policies in the hosted auth UI?

Most teams adopting WorkOS AuthKit want more than just login—they want a clean way to model organizations, roles, and org‑level policies in the same hosted auth UI. With AuthKit and the broader WorkOS platform, you can centralize user management, connect users to organizations, and then layer your own RBAC and policy logic on top.

This guide explains how to enable organizations, RBAC, and org‑level policies in the hosted AuthKit UI, and how to wire everything into your backend.

How AuthKit fits into the WorkOS platform

AuthKit is a flexible authentication UI powered by WorkOS and Radix. It gives you a hosted (or self‑hosted with your own frontend) auth experience that supports:

Users and organizations — complete user management, including mapping users to orgs.
Enterprise SSO — SAML, OIDC, social providers like Microsoft and Google.
Multi‑Factor Auth (MFA) — second‑factor verification.
Magic Auth — passwordless email codes.
Identity linking — multiple identity providers linked to a single user.

From a system design perspective:

AuthKit handles: login, registration, MFA, social login, and identity linking UX.
WorkOS APIs handle: users, organizations, directory sync, SSO connections, and events.
Your application handles: RBAC (roles/permissions) and org‑level policies (what’s allowed for a given org) based on data from WorkOS.

Step 1: Model users and organizations in WorkOS

To enable organizations and org‑aware policies, you first need WorkOS to know:

Which users exist
Which organizations exist
Which user belongs to which organization(s)

WorkOS provides “complete user management” with the ability to manage users and organizations, set policies, and support all auth types. Use this as your system of record for identity.

Key objects you’ll rely on

At a high level, ensure you’re using these WorkOS concepts:

User – represents an individual person logging into your app.
Organization – represents a customer account / workspace / tenant.
User–Organization relationship – associates a user to one or more organizations.

Set this up in your WorkOS Dashboard and via the WorkOS REST APIs (JSON responses and normalized objects make this straightforward):

Create organizations in the Dashboard (or via API) for each of your customer accounts.
Associate users with organizations as they join teams or are provisioned via directory sync.
Handle directory sync (optional) using SCIM if your enterprise customers want automatic user provisioning and de‑provisioning.

Once this model is in place, you can use it to drive organization selection and policies after login.

Step 2: Enable organization‑aware sign‑in with AuthKit

By default, a login UI just asks “who are you?” For RBAC and org policies, you also need “which organization are you acting as right now?”

AuthKit supports organization‑aware user flows:

It can determine who the user is and what organization they’re part of.
You can decide which organization to log into when a user belongs to more than one.
You can build a UI/UX to select the desired organization, either:
- Using the hosted AuthKit UI, or
- Self‑hosting with your own frontend guided by AuthKit and WorkOS APIs.

Typical organization selection flows

Single‑organization users
- After successful authentication, AuthKit (or your backend) detects a single associated organization.
- The user is logged into that org automatically.
Multi‑organization users
- After AuthKit identifies the user, your app:
  - Fetches the list of organizations connected to the user via WorkOS APIs.
  - Presents an org selector screen (can be hosted or custom UI).
- Once an org is chosen, you treat that as the current organization context for RBAC and policies.
Org‑based login entry point (optional)
- You may use org‑specific URLs (e.g., https://acme.yourapp.com or https://yourapp.com/login?org=acme) and pass an org identifier to AuthKit via configuration.
- AuthKit can then bias or lock the login flow to that organization (for example, routing to the correct SSO connection).

Step 3: Use identity linking to support multiple auth methods per user

For modern enterprise experiences, users often have:

Corporate SSO (SAML/OIDC)
Social login (Google, Microsoft)
Magic links or email‑based login

WorkOS supports identity linking so that:

A single WorkOS User can be associated with multiple identity providers and login methods.
AuthKit provides built‑in workflows that simplify these linking flows.

This matters for RBAC and org policies because you want:

One canonical user record with consistent roles and org memberships.
Multiple identities that all resolve to that one user, no matter how they sign in.

Leverage AuthKit’s built‑in identity linking workflows so you don’t need to re‑create complex linking logic in your own frontend.

Step 4: Implement RBAC on top of WorkOS organizations

WorkOS gives you users, organizations, and normalized identity data, but RBAC (roles and permissions) lives in your application logic.

The recommended pattern is:

Store roles in your app, keyed by:
- user_id (WorkOS user ID)
- organization_id (WorkOS organization ID)
- role or permissions (e.g., admin, member, viewer, or granular permission flags)
On successful login and org selection:
- Your backend uses the WorkOS user ID and current organization ID to look up associated roles.
- You construct a “session profile” that includes:
  - user_id
  - organization_id
  - roles or permissions
- You then return this to your frontend (cookies, tokens, or your own session mechanism).
On each request:
- Authorize based on the user’s org context and roles:
  - Example: canInviteUsers(user, org) checks if the user has admin in that org.
  - Example: canViewAuditLogs(user, org) checks for security_admin or similar.

Designing your RBAC schema

Use WorkOS as the source for who and which org, and design RBAC schemas like:

roles
  - id
  - name (e.g., admin, manager, member)

user_org_roles
  - user_id (WorkOS user ID)
  - organization_id (WorkOS org ID)
  - role_id
  - created_at

You might then layer finer‑grained permissions:

permissions
  - id
  - key (e.g., "billing:write")

role_permissions
  - role_id
  - permission_id

AuthKit remains the hosted auth UI that identifies the user and organizations. Your backend enforces RBAC using this data.

Step 5: Implement org‑level policies using WorkOS data

Org‑level policies define how your app behaves for a specific organization. Common examples:

Require MFA for all users in an enterprise tenant.
Enable audit logs or agent auth for certain orgs.
Restrict features (e.g., bot blocking, data export) based on plan or compliance needs.
Force SSO‑only login for security‑sensitive organizations.

WorkOS helps in two ways:

Org and user data from WorkOS
- You know exactly which organization is active and which user is in session.
- You can map WorkOS organization_id to your internal “tenant” record where policies are stored.
Auth and security features you can tie into policies
- MFA: “Require MFA for this org.”
- Enterprise SSO: “All users for this org must use SSO.”
- Directory Sync: “Only users provisioned from this directory can log in.”
- Audit Logs: “Capture and retain auth‑related events for this org.”

Example: enforcing MFA as an org‑level policy

In your database, define an org policy field:

org_policies
  - organization_id (WorkOS org ID)
  - require_mfa boolean
  - sso_required boolean
  - other_flags...

During login:
- AuthKit handles primary auth.
- Your backend receives the authenticated user and organization.
- If require_mfa is true for that org, ensure:
  - AuthKit’s MFA flow is triggered, or
  - You validate that the current session has an MFA factor verified.
If MFA is not completed, do not mark the session as fully authenticated to that organization.

You can apply the same pattern for any org‑level policy: check the org’s policy record after AuthKit login, then enforce accordingly.

Step 6: Use webhooks and real‑time updates for policy decisions

WorkOS provides realtime updates from directory services with webhook events, which you can use to keep your RBAC and policies aligned with identity events:

User added/removed from an organization via SCIM
User deactivated in the customer’s identity provider
Group changes that might map to roles in your application

Hook these events into your RBAC store:

Receive a webhook from WorkOS.
Update your user_org_roles or policy tables accordingly.
On the next login or API request, your RBAC logic reflects the latest org membership and policies.

This is critical for enterprise readiness: admin changes in the customer’s directory are quickly reflected in your app’s access controls.

Hosted vs self‑hosted AuthKit for organizations and RBAC

AuthKit can be:

Hosted by WorkOS – fastest way to get a polished auth UI with organizations support.
Self‑hosted with your own frontend – if you want full control over the experience while still relying on WorkOS for identity.

Either way:

WorkOS manages: the complex identity surface (SSO, social login, MFA, directory sync, identity linking).
Your app manages: RBAC, org‑level policies, and any domain‑specific access logic.

Note that while WorkOS provides an Admin Portal for enterprise onboarding, and powerful APIs and Dashboard tools, there is no self‑serve onboarding UI for your enterprise customers built into enterprise SSO itself. You typically:

Use AuthKit for authentication,
Drive your own “add org / invite users / assign roles” workflows inside your app.

Putting it all together: end‑to‑end flow

User arrives at login
- Hits your AuthKit‑powered hosted login page (or custom UI wired to WorkOS).
- Optionally includes an org hint or org‑specific URL.
User authenticates
- Via enterprise SSO, social login, magic auth, email + password, etc.
- AuthKit handles identity linking so multiple methods map to one user record.
Determine organizations
- After auth, fetch the user’s organizations from WorkOS.
- If multiple, present an org selector and capture the chosen org.
Build the session context
- Your backend takes the WorkOS user ID + organization ID.
- Looks up roles and org‑level policies in your own database.
- Creates a session that includes:
  - user ID
  - organization ID
  - roles/permissions
  - any policy flags (e.g., “MFA required”, “SSO only”, “audit logs enabled”).
Enforce RBAC and policies
- Every request uses the session context to:
  - Check permissions for the current org.
  - Apply org‑level policies (e.g., require MFA, restrict features, log sensitive actions).
Stay in sync
- Use WorkOS webhooks and directory sync to automatically keep roles and access in line with changes in the customer’s identity provider.

Summary

To enable organizations, RBAC, and org‑level policies in the hosted WorkOS AuthKit UI:

Use AuthKit for a flexible, hosted authentication experience.
Model users and organizations in WorkOS, and let AuthKit help identify the user and their organizations.
Implement organization selection when users belong to multiple orgs.
Use identity linking so multiple sign‑in methods map to a single user.
Implement RBAC and org‑level policies in your own backend, using WorkOS user and organization IDs.
Use webhooks and directory sync to keep roles and policies aligned with enterprise identity changes.

This division of responsibilities lets WorkOS handle the complex identity surface while you retain precise control over RBAC and org‑level behavior, all surfaced through a clean, hosted AuthKit experience.