SigNoz is an open-source, OpenTelemetry-native observability platform for your team and their AI agents. Get logs, metrics, and traces in one tool with features like APM, distributed tracing, log management, infra monitoring, etc. Combined with SigNoz MCP and a native AI teammate (in SigNoz Cloud) it helps you build more resilient apps.
AuthZ Guide
How to structure a page so it works with the permission system.
We are migrating from the ADMIN | EDITOR | VIEWER roles to per-action checks. Instead of granting VIEWER and
exposing everything, a user can now be granted access to a single resource, eg: Logs only.
Prerequisites
Check whether the resource your page represents is supported: see permissions.type.ts for the current resources and their allowed verbs.
If the resource is not listed there, skip authz for now. The backend does not enforce it yet, so any frontend check would be decorative. Revisit once the resource is generated into that file (it is auto-generated from the backend).
Core rules
These hold for every page. The per-pattern sections below only add to them.
- A page is always reachable, regardless of permission. The intended action must be known before permission can be checked, so the route renders first and individual pieces are gated.
updaterequires bothreadandupdate. A user who can write but cannot read the current value must not get an edit affordance.deleteis independent ofread. Delete controls stay visible for a user who holdsdeletebut notread.- Never gate per row. If a user can
list, render every row. Checkreadonly when the row is opened (drawer or detail route). - Gate the narrowest thing that works, a button over a section, a section over a page.
- Gate a page on
readalone. It is the only verb the page's own request needs.updateanddeletegate individual controls, so waiting for them holds up the whole page for nothing — pass them aspreloadChecksand they resolve in the same request, leaving the controls to read from cache.
- Gate a page on
- A resource may be gated while a sub-resource is not. A user without
readon Service Accounts can still holdcreateon API Keys, so blocking the outer container would hide work they are allowed to do. - Verbs not covered here (
attach,detach,assignee) behave likedelete: gate the control that triggers them, not the surrounding content. - Expose the selector. A role is scoped to a resource by pasting its selector into the role editor, so every
resource a role can be scoped to shows that selector with a copy control on its detail view or drawer. The selector
is whatever the editor accepts for the resource (dashboard ID, service account ID, role name, ...), listed per
resource in permissions.config.ts. It is already known from
the row or URL, so it stays visible and copyable without
read. Reference: the ID field in ServiceAccountDrawer/OverviewTab.tsx.
Page patterns
List page
Without list, but with any of read / create / update, the table and
everything that only feeds it are blocked:
- Title, description, search, filters and action buttons stay visible. Nothing is hidden for lack of permission.
- Disable what only shapes the blocked request — the search box, the filter chips, a Clear button — and give it the same denial. It edits a query that has nowhere to run, so leaving it live invites the user to compose a filter and watch nothing happen.
- Gate a region as one section when several of its controls are dead. A saved views rail is a block with a single callout, not a column of identical tooltips; a row of filters is one tooltip zone, not one per control.
- The create button stays enabled if the user holds
create. It is independent oflist.
Edit page
Without read:
- Block the content with
withAuthZContent, not the whole route. - Keep delete visible (rule 3).
- Keep update blocked (rule 2).
Drawer
Without read:
- Block the drawer body, not the drawer itself.
- Prefer routing that carries the resource ID in the URL, so delete stays reachable without
read. - Keep update blocked (rule 2).
- Watch for sub-resources the user may still be allowed to act on (rule 6).
Create
Without create:
| Entry point | Gate with |
|---|---|
| Button | AuthZButton |
| Dedicated create page | withAuthZPage |
| Create drawer opened directly (deep link) | withAuthZContent on the body + AuthZButton on footer actions |
Delete
Gate the control with AuthZButton, or AuthZTooltip for a non-button trigger such as an icon or menu item.
Quick filters
What "blocked" means
Blocking is always a visible denial, never a silent removal. Use the components in
lib/authz/components rather than hand-rolling a check, they carry the
denial message and the loading state.
Denial copy comes from the components. Never write a custom message for a permission check. disabledTooltip is
for a block that is not a permission — a lock, an immutable resource, a mount that is deliberately read-only. It
takes precedence over the checks, which are then skipped, so set it only when that block is the real obstacle: a
missing permission must still surface its own wording.
| Scope | Component | Denied state |
|---|---|---|
| Button | AuthZButton |
Disabled + tooltip |
| Any element | AuthZTooltip |
Disabled child + tooltip |
| Section | withAuthZContent / AuthZGuardContent |
Inline PermissionDeniedCallout |
| Page / route | withAuthZPage / AuthZGuardPage |
PermissionDeniedFullPage |
| Custom fallback | withAuthZ / AuthZGuard |
Whatever you pass as fallback |
Prefer the HOC (withAuthZ*); reach for the JSX guard (AuthZGuard*) when the gate depends on conditional rendering
and an HOC cannot express it. The components README has the full decision tree and how to build the checks array.
Migration checklist
Use the existing components. Create a new one only if none fit.
- Can I apply a
withAuthZ*variant directly, or must I extract the content into a component first?- If extraction is needed, declare the new content component in the same file to keep the diff small, then move it to its own file in a follow-up commit or PR.
- Is the layout structured to respect the core rules?
- If not, raise it in the frontend Slack channel before reshaping the page.
- Am I gating a shared component rather than a page or section?
- If so, it must stay functional with no permission. Example: the Query Builder works without field suggestions when the user cannot read them.
- Does the page expose the resource's selector with a copy control (rule 8)?
- The expected format is the
selectorPlaceholderfor the resource inpermissions.config.ts.
- The expected format is the
Testing
Devtool
Press Cmd + K (Ctrl + K on Windows/Linux) to open the shortcuts, search for AuthZ, and pick the first
result. The devtool simulates granted and denied permissions across the UI.
Available only in local development, it is stripped from production builds.
Unit tests
lib/authz/utils/README.md covers the *.authz.test.tsx naming convention, the
MSW handlers (setupAuthzAdmin, setupAuthzDenyAll, setupAuthzDeny, setupAuthzAllow,
setupAuthzGrantByPrefix), and how to test the loading state.