Skip to main content

User Roles & Invites

Feature row 9 — Sprint LIC Phase 2

Team Management is included on the Enterprise plan. Trial and Professional tenants start with a single admin account.

The four roles​

Behavry has four human user roles, ordered from least to most privileged:

RoleCan doCannot do
viewerRead dashboards, audit events, agents, policiesEdit anything
analystEverything viewer can + acknowledge escalations, release quarantine items, add annotationsEdit policies, invite users
policy_authorEverything analyst can + edit policies, inbound rules, DLP patternsManage users, billing, deployment settings
adminEverything. Invite / remove users, change plan, rotate credentials(nothing gated below admin)

Role hierarchy is enforced at the API layer:

ROLE_HIERARCHY = {
    "viewer": 1,
    "analyst": 2,
    "policy_author": 3,
    "admin": 4,
}

Any route that needs a minimum role uses require_role("analyst") (or higher) as a FastAPI dependency. A user cannot assign a role higher than their own.

Invite flow​

1. Admin initiates​

Settings → Users → Invite opens a form: email, initial role. On submit:

  • A record is created in admin_users with status=invited
  • An invite token is generated and emailed to the address (if SMTP is configured) or surfaced in the UI for manual delivery

2. Invitee accepts​

The invite link lands on the sign-in page with the token in the query string. If the tenant uses Clerk, the invitee signs up through Clerk and is auto-linked to the pending invite. If the tenant uses password auth, the invitee sets a password on first visit.

On accept, the user's status flips to active and a user.activated audit event is written.

3. Role takes effect​

The user's next API call carries a token with their role claim. All subsequent authorization checks see the new role immediately — no re-login required.

Deactivation​

Admins can deactivate a user at any time. Deactivation is reversible: the user row stays, their status flips to deactivated, and all active sessions are invalidated. Reactivating restores the previous role.

Hard delete is deliberately not exposed in the UI to preserve audit trail references.

API​

Routes: backend/behavry/admin/user_routes.py (prefix=/api/v1/admin/users).

MethodPathPurpose
GET/api/v1/admin/usersList users in the tenant
POST/api/v1/admin/usersInvite a new user
GET/api/v1/admin/users/{id}User detail
PATCH/api/v1/admin/users/{id}Update role or status
POST/api/v1/admin/users/{id}/resend-inviteResend the invite email
DELETE/api/v1/admin/users/{id}Deactivate the user

SSO-sourced users​

When the tenant is configured with OIDC or SAML (see Authentication), users are auto-provisioned on first sign-in. The role they land in is determined by:

  1. An explicit role attribute in the SSO assertion (role, groups, or a custom mapping), OR
  2. The tenant's default SSO role (set under Settings → SSO; typically viewer)

Admins can promote SSO-sourced users after first sign-in.