Troubleshoot permissions

Goal

Diagnose missing screens, disabled buttons, and API authorization errors.

Who it is for

Tenant admins (member.admin) helping users; managers confirming role intent.

Decision guide

What you see	Meaning	Fix
Nav item missing / redirect to dashboard	SPA meta.permission or meta.module failed	Grant key or enable module; user refreshes session
API 403	Gate / authorize denied or missing Public API api:* ability	Add permission or token ability
API 404 on a known UUID	RLS / other tenant / not visible	Wrong tenant token or record truly absent
API 422	Module disabled or domain validation	Enable module or fix business fields
Portal cannot open staff URL	Different principal	Use portal login / invite

Steps

1. Confirm the user membership and role on Members.
2. Open Members setup → Permission matrix and verify keys (sales.post, bank.manage, …).
3. Check Modules entitlements for the tenant.
4. Ask the user to sign out/in (or soft refresh) so /me enabled modules & permissions reload.
5. For integrators, verify Sanctum abilities include tenant:{uuid} and the needed api:* keys.

Result

Access matches the intended role; remaining failures are data/domain issues, not auth.

Related

• Permissions model
• Users and roles
• Integrator hub