Permission denied — what to do

A "Permission denied" error means the user's role doesn't grant the action they tried. CargoSurge's RBAC is per-module, per-action, so the fix is usually a role change — not a code change.

Where this shows up

Common surfaces:

• Pages return 403 in the browser when a user clicks a sidebar link they don't have access to.
• Buttons are hidden for users without permission to perform an action.
• API responses with 403 PERMISSION_DENIED for users hitting an endpoint they can't access.
• "Loading…" spinners that never resolve — usually because a background data fetch was blocked by 403 and the page can't render without it.

Step-by-step diagnosis

1. 1
   What was the user trying to do? Be specific — "open Settings → Subscription" is different from "create a quotation".
2. 2
   What's their current role? Settings → Users → find the user → Role column.
3. 3
   Look up the role in the Roles & Permissions Matrix. Confirm whether their role has the relevant permission.
4. 4
   If the role is right but they're still blocked, check branch scope — maybe the record they're trying to access is in a branch they're not assigned to.
5. 5
   If everything looks right, verify the user's session — they may need to log out and back in for a recent role change to take effect.

Common scenarios

"Operator can't see vehicle types in the dropdown"

This was a real bug — fixed in commit 6167b630. If you're on an older deployment, the master-data endpoints required admin module VIEW which operator doesn't have. Update to the latest version.

"Sales user can't create an invoice"

Correct — sales role has VIEW on finance, not CREATE. Either:

• Promote the user to operator (forwarding + finance VIEW + reports VIEW) if they need to invoice their own deals.
• Or have an accountant create the invoices on the sales user's behalf.

"Forwarding operator can't see customers in the picker"

forwarding_operator doesn't have CRM access. Two options:

• Use operator instead, which includes CRM VIEW.
• Or expose customer search on the booking form via a different endpoint (this is on the roadmap).

"Driver tries to log into web — gets blocked"

driver role is mobile-only. Web login is intentionally blocked. They need the Driver mobile app — see Driver app.

"Admin user gets 403 on a platform admin page"

tenant_admin and admin roles cover tenant-scoped admin. Platform admin (the global super-admin views at /platform/...) requires the separate SUPER_ADMIN role and is not granted to tenant users. If a tenant admin is hitting /platform/... URLs, they're in the wrong place.

Common pitfalls

Reporting a permission bug

If you genuinely believe an endpoint is gated wrong (e.g. operators can't access something they should), email [email protected] with:

• The user's role.
• The exact action and URL that failed.
• A screenshot of the error.

Custom roles aren't supported on Starter/Team plans; Pro+ tenants can request role customisation through their CSM.