diff --git a/src/collections/sistent/components/permission/code.mdx b/src/collections/sistent/components/permission/code.mdx
new file mode 100644
index 00000000000000..6945d22132ddba
--- /dev/null
+++ b/src/collections/sistent/components/permission/code.mdx
@@ -0,0 +1,173 @@
+---
+title: Permission Code
+component: permission
+description: Integration details, code examples, and API references for the PermissionShield component.
+---
+
+import { PermissionShield, Button, PermissionSessionContext } from "@sistent/sistent";
+
+The `PermissionShield` component acts as a high-level wrapper to restrict and decorate interactive components.
+
+> **Important Security Note:** UI gating is a presentation-layer control only. Client-side checks must not decide access. The backend server and API routes must always enforce authorization on every request.
+
+
+
+
+
+Wrap any standard component (e.g., a `Button`) inside the `PermissionShield` to automatically overlay the lock badge when permissions are restricted.
+
+
+
+
+Use the `boundaryPadding` prop to configure custom offsets if the tooltip overlaps fixed elements (like headers, sidebars, or navbar sections) during scrolling.
+
+
+
+
+The `PermissionShield` component should be used to protect actions or affordances that require specific roles, permission keys, or capabilities.
+
+> **Important Security Note:** UI gating is a presentation-layer control only. Client-side checks must not decide access. The backend server and API routes must always enforce authorization on every request.
+
+
+
Wrap gated interactive components (Buttons, IconButtons, Tabs) to provide visual feedback to users when they are restricted.
+
Ensure the locked state clearly informs the user which permissions are missing, reducing frustration and confusion.
+
Use responsive layouts or custom boundary paddings where the tooltips might get clipped by sidebars or sticky headers.
+
+When deciding whether to restrict a feature, follow these design system guidelines:
+
+
+
+ Disable (Keep Visible with PermissionShield): Use this when the action is part of a standard page flow (like a "Delete Connection" button). Keeping it visible helps users understand that the feature exists, and the lock badge tells them exactly why they cannot click it and who to contact.
+
+
+ Hide (Remove from Layout): Use this when the user has absolutely no access to the entire page or section (e.g. an "Admin Console" menu link or a full tab panel that they do not have clearance to view).
+
+
+
+
Tooltip versus Card Layouts
+
+When displaying permission details using `PermissionSessionContext`, choose the variant based on the integration context:
+
+
+
+ Tooltip Layout (default): Use this inside popovers, hover tooltips, and overlay badges (e.g., within `PermissionShield`) to display compact, dark-background metadata without displacing layout elements.
+
+
+ Card Layout: Use this when embedding permission details directly into the page layout, such as full-page 403 authorization error layouts, settings sidebars, or container panels.
+
+ Consistent Badge Placement: Use `'inline'` (default) to place the lock badge at the center-right of the component (common for text fields, buttons, and inline controls). Use the `'badge'` variant to overlay the badge at the bottom-left corner of the parent component when appropriate (e.g., custom cards, list items, or standalone elements).
+
+
+ Accurate Tooltips: Ensure the `permissionKey` prop is fully populated with accurate names so the tooltip can display the exact missing keys.
+
+
+ Nested Disabled Controls: Do not rely solely on the wrapper to block interactions. Set the nested control (e.g. Button) to `disabled` (or `aria-disabled` for custom controls) and handle `preventDefault()` where needed so that default actions, keyboard accessibility, and screen readers behave correctly.
+
+
diff --git a/src/collections/sistent/components/permission/index.mdx b/src/collections/sistent/components/permission/index.mdx
new file mode 100644
index 00000000000000..20a61e34374e4a
--- /dev/null
+++ b/src/collections/sistent/components/permission/index.mdx
@@ -0,0 +1,112 @@
+---
+name: "Permission"
+title: "Permission"
+published: true
+component: permission
+description: The PermissionShield component gates and protects interactive actions, buttons, and navigation elements. It displays a visual lock icon overlay or inline badge when a user lacks the necessary permission keys or capabilities.
+---
+
+import { PermissionShield, Button, PermissionSessionContext } from "@sistent/sistent";
+
+The `PermissionShield` component provides a standard design pattern for feature-level permission gating across applications. Rather than silently hiding disabled elements, it keeps them visible (preserving layout continuity) and overlays a visual lock indicator to explain to users why the action is restricted.
+
+> **Important Security Note:** UI gating is a presentation-layer control only. Client-side checks must not decide access. The backend server and API routes must always enforce authorization on every request.
+
+
+
+
+
+The default variant (`'inline'`) wraps any standard action component (like a `Button` or `IconButton`) and places a lock icon badge at the center-right of the target element (serving as an end adornment). When clicked, it shows a detailed explanation of the missing permission.
+
+
+
+
+
+
+The badge variant (`'badge'`) renders the permission badge overlaying the bottom-left corner of the target element. This is useful for list items, settings tables, or static text where placing the shield as an end-adornment on the right is not suitable.
+
+
+
+
+
+
+The `PermissionSessionContext` component renders the detailed authorization metadata (user identity, organization, assigned roles, and missing keys) that is displayed inside tooltips or cards. It supports two layout variants:
+
+- **Tooltip Variant (`'tooltip'`):** A compact layout designed to fit inside standard hover/click tooltips (used by default inside `PermissionShield`).
+- **Card Variant (`'card'`):** A theme-aware, scaled-up layout designed to be embedded directly into custom cards, sidebars, or full-page 403/Forbidden error screens.
+
+### Tooltip Layout
+
+
+
+