The Permissions component suite provides a unified, declarative authorization architecture for cloud-native user interfaces. Rather than scattering manual permission checks throughout codebases, Sistent delivers a cohesive system of providers, visual shield wrappers, native component props, contextual 403 cards, and multi-tenant organization hooks.

Architecture & Building Blocks

The Sistent Permission System is built on core pillars:

  1. PermissionProvider: The root context provider supplying authorization evaluators (userHasPermission) and active user context (userContext) to the entire component tree.
  2. PermissionShield: The declarative UI wrapper that overlays actionable tooltips onto unauthorized affordances without losing discoverability.
  3. Native Component Props (permissionKey & permissionAction): Direct gating support built into Sistent base components (Button, IconButton, MenuItem, ListItem, ListItemButton).
  4. PermissionSessionContext: The standalone authorization context component displayed inside tooltips and on dedicated 403 error pages.
  5. useAccessibleOrgs: The multi-tenant organization switching hook for 403 error views.

Shield Variants

PermissionShield offers two distinct presentation variants depending on the layout and density of the guarded element:

Inline Variant (Default)

The Inline variant centers a security shield trigger on the right side of the guarded element. It is ideal for full-width buttons, form inputs, list items, and standard rectangular controls.

Badge Variant

The Badge variant renders a compact shield badge anchored to the corner of the guarded affordance. It is designed for icon buttons, compact toolbars, chips, and standalone action pills.

Native Component Gating

In addition to wrapping elements with <PermissionShield>, Sistent base components natively accept permissionKey and permissionAction props:

  • Button
  • IconButton
  • MenuItem
  • ListItem & ListItemButton

When permissionAction="showShield" (the default), the component automatically wraps itself in PermissionShield. When permissionAction="hide", the component automatically renders null if the user lacks the required permission.

Permission Session Context Card (403 Pages)

When users navigate directly to a restricted URL or access-denied route, PermissionSessionContext renders as a full-page card variant. It provides complete transparency into the missing keys, categorized tags, and assigned roles.

Authorization Required

Missing requisite key

Create Workspace

Create and configure collaborative workspaces within an organization.

Workspace Management
Configuration
Key Reference

User

Ada Lovelace

Org

Layer5 Cloud

Role(s)

Team Member

Seeing this message in error? Contact your Admins to request access.

Authorized State (Pass-Through)

When the active user possesses the required permission key, PermissionShield seamlessly passes through the child component without dimming, overlaying icons, or intercepting pointer events.

Key Features
  • Declarative Key Specs: Accepts single permission keys or composite logical sets (anyOf / allOf).
  • Native Component Integration: Pass permissionKey and permissionAction directly to Button, IconButton, MenuItem, ListItem, and ListItemButton.
  • Interactive Key Copying: Users and administrators can copy the exact permission UUID to clipboard with one click.
  • Assigned Role Clarity: Context cards show the user's actual assigned roles in the active organization, preventing confusion with the global role catalog.
  • Conflict-Free Tooltips: Global event coordination guarantees only one shield tooltip is open across the entire interface at any time.
  • Multi-Tenant Org Switching: Pairs with the useAccessibleOrgs hook to guide users to switch to an authorized organization.