# Role rules

Role rules are managed through `/v1/role_rules` with `policies:read` or `policies:write`. Business supports up to 100 rules; Enterprise supports up to 1,000 and bounded expression conditions. The selected role is application data, not an OhAuthCat account or staff permission.

## Rule order

Matching classes are evaluated in this order:

1. Group rules.
2. Exact organization-verified primary-email domain rules.
3. Connection-default rules.

Within a class, ascending priority and then stable rule ID select the role. Conditions that evaluate false do not match. A matched explicit deny refuses sign-in; a role assignment cannot override an admission refusal. Values are bounded to 128 bytes.

The optional result travels in the profile through code exchange and access-profile reads. No match means no role, and a newer unmatched sign-in clears the previously stored role rather than keeping an old permission indefinitely. Existing rules remain enforced after downgrade; above-plan edits are refused and deletion remains available.

## Conditions

A rule can carry an optional `condition`: an `allow` or `deny` action over a bounded expression. Expressions combine `leaf`, `all` and `any` nodes over `email`, `email.domain` and `groups.idp`, using `equals`, `in`, `contains` and `contains_any`. They are the same declarative expressions as [sign-in policies](/sso/sign-in-policies/), not code or regular expressions. A rule matches only when its match key matches and its condition holds.

## Preview

POST `/v1/role_rules/preview` (scope `policies:read`) shows the role a sign-in would get, without signing anyone in. Send an `organization`, a `connection` and sample evidence: `email` and `email_verified`, `idp_groups` and `idp_groups_verified`, and `scim_groups`. Add an unsaved `draft` rule to see its effect before you save it.

The preview uses the same compiler, ordering and condition evaluator as sign-in. The verified domain comes from the organization's verified domains, as it does at sign-in. The response gives `role` (null when no rule assigns one) and `denied`, which is true when a deny rule matched and the sign-in would be refused. Nothing is stored or audited, and the plan limits for saving rules do not apply to a draft.

## Directory roles can differ

Directory projection uses current SCIM memberships, exact organization-owned primary-email domains and a connection default only when exactly one connection is bound to the directory. No binding or several bindings skip the connection-default class.

Shared eligible evidence must produce the same role as sign-in. This does not imply universal parity: authenticated IdP group claims and OIDC `email_verified` are sign-in-only evidence and are unavailable to directory events. Ambiguous, unavailable or overflowing SCIM evidence also cannot establish a shared identity match.

Direct user changes recompute the role before their normal user event. Rule, membership, binding or domain changes trigger bounded worker reprojection, so cached directory roles can update eventually. A role-only change uses the normal user-updated event rather than a separate permission event.

Your application must decide which identity source controls its own permissions and revoke access when eligibility changes. See [directory role mapping](/directory-sync/role-mapping/), [sign-in policies](/sso/sign-in-policies/) and [profiles](/sso/profiles/).
