Permissions
Implementation examples, props specifications, hooks, and integration code for PermissionShield, PermissionProvider, PermissionSessionContext, and useAccessibleOrgs.
The Permissions module in Sistent provides declarative authorization abstractions that integrate directly with @meshery/schemas/permissions and host ability evaluators.
1. Mounting PermissionProvider
Mount PermissionProvider at the root of your application. Supply the authorization check function (userHasPermission) and the user's active session metadata (userContext).
Active Permission Context
2. Native Gating: Button & IconButton
Pass permissionKey and permissionAction directly to Button or IconButton. When unauthorized, permissionAction="showShield" automatically wraps the button in PermissionShield, while permissionAction="hide" renders null.
3. Native Gating: MenuItem, ListItem, and ListItemButton
MenuItem, ListItem, and ListItemButton natively evaluate permissions and attach inline shield tooltips or hide themselves cleanly when unauthorized.
4. Wrapping Custom Elements with PermissionShield
For custom cards, containers, or non-base components, wrap the element with <PermissionShield>.
Publish Design to Catalog
Share architectural patterns with the community catalog.
5. Composite Keys (anyOf / allOf)
Affordances requiring either multiple alternative keys or all of several keys can pass a PermissionKeySet.
6. PermissionSessionContext (403 Pages)
Render PermissionSessionContext with variant="card" inside access-denied boundaries. It self-resolves the unmet keys and renders full user context.
Authorization Required
Missing requisite key
Create Workspace
Create and configure collaborative workspaces within an organization.
User
Ada Lovelace
Org
Layer5 Cloud
Role(s)
Team Member
Seeing this message in error? Contact your Admins to request access.
7. Multi-Tenant Hook: useAccessibleOrgs
Use useAccessibleOrgs to query the user's alternative organizations in parallel and populate an organization switcher on 403 error pages.
Switch to an Accessible Organization
Select an organization where you have access to this resource:
Layer5 Engineering (2 roles assigned)
Component API & Props
Base Component Permission Props
Components including Button, IconButton, MenuItem, ListItem, and ListItemButton accept the following props:
| Prop | Type | Default | Description |
|---|---|---|---|
permissionKey | PermissionKeySpec | undefined | Permission key or key set. When omitted, the component renders normally without gating. |
permissionAction | 'showShield' | 'hide' | 'showShield' | When unauthorized, 'showShield' attaches PermissionShield and 'hide' renders null. |
PermissionShieldProps
| Prop | Type | Default | Description |
|---|---|---|---|
permissionKey | PermissionKeySpec | required | Single Key or composite anyOf / allOf key set. |
children | React.ReactNode | required | The affordance or child component to guard. |
variant | 'inline' | 'badge' | 'inline' | Visual placement of the shield trigger icon overlay. |
PermissionSessionContextProps
| Prop | Type | Default | Description |
|---|---|---|---|
variant | 'tooltip' | 'card' | 'tooltip' | Visual theme and sizing variant (compact tooltip vs. full-page 403 card). |
permissionKey | PermissionKeySpec | undefined | Self-resolving key or key set. Resolves missing keys from nearest PermissionProvider. |
displayedKeys | Key[] | undefined | Pre-resolved array of permission keys to display. |
subtitle | string | undefined | Custom requirement subtitle (e.g. "Needs any of: ..."). |
categories | string[] | undefined | Category chip labels. |
subcategories | string[] | undefined | Subcategory chip labels. |
PermissionProviderProps
| Prop | Type | Default | Description |
|---|---|---|---|
userHasPermission | (key: Key) => boolean | required | Authorization evaluator function provided by the host application (e.g., CASL canKey). |
userContext | PermissionUserContext | undefined | Active session metadata containing userName, orgName, and roleNames. |
children | React.ReactNode | required | Root application sub-tree. |
