Skip to content

Roles and permissions

The catalog

Every permission is declared once, in Go, in internal/authz/catalog.go:

{Name: PermBranchCreate, Group: "branch", Description: "Can create branches"},
{Name: PermRoleInternalCreate, Group: "role", IsSystem: true, Description: "Can create new internal roles"},

ims permission:sync upserts the catalog into the permissions table (run it after adding one; make seed does too). The generated permissions reference lists all of them with the seeded roles that hold each.

  • System permissions (IsSystem: true) are platform-only: they are never granted to tenant roles and cannot be edited from tenant surfaces.
  • Name them <resource>.<action> — product.view, product.view.all, product.create, product.update, product.delete.

Roles

Role Scope Holds
Super-Admin platform (system role) bypasses every check — Checker.Can returns true
Developer platform the dev.* permissions (developer dashboard)
Admin per tenant the tenant-level groups: role, branch, user, setting, activity
custom roles per tenant whatever a tenant admin assigns

Every new tenant gets its Admin role from authz.AdminTenantPermissions(). Add a group to that list (as the tutorial does for product) and new tenants’ admins get it.

Invariants the services enforce for every caller: the Super-Admin cannot be stripped of its role or deleted, users cannot escalate their own roles, and system roles are immutable from tenant surfaces.

Where permissions are checked

On the route, like Laravel’s can: middleware:

r.With(h.can(authz.PermBranchCreate)).Post("/branch", h.store)

Inside a handler only when the permission depends on the payload:

if err := h.checker.MustCan(r.Context(), authn.UserID(r), authz.PermUserRoleAssign); err != nil {
h.Error(w, r, err)
return
}

Not in services, jobs, commands or scheduled tasks. Those are trusted code (decision 23). A service that needs a Gate-style decision — “may this actor touch that record?” — takes an *authz.Checker explicitly.

Caching

Checker caches each user’s permission set for 10 minutes and invalidates it whenever roles or permissions change through the API. If you change roles directly in the database, run ims cache:clear.

The safety net

internal/app/route_permissions_integration_test.go walks the live router and asserts that a token without permissions is refused on every protected route. A route mounted without h.can(...) fails CI. Routes deliberately open to every authenticated user (your own profile, notifications) are listed in that test’s allowlist with a reason.

Managing roles through the API

Endpoint Permission
GET /api/v1/role, GET /api/v1/role/{id} role.view.all, role.view
POST /api/v1/role, PATCH /api/v1/role/{id}, DELETE /api/v1/role/{id} role.create, role.update, role.delete
POST /api/v1/user/assign-role user.role.assign
GET /api/v1/permission permission metadata (tenant-exempt)

The developer dashboard’s Inspector → Roles & permissions shows the live catalog, every role and any drift between the catalog and the database.