Role & Permission Management

The authorisation model is built on capabilities, not roles. Each endpoint declares the capabilities it requires (e.g. competitions:create, members:read, finance:export); the auth middleware looks up the caller's effective capability set and denies any request whose required capabilities are not present. Roles are convenience containers: a role document holds a list of capabilities (with wildcard support such as competitions:* or *:read), and assigning a role to a user grants the union of its capabilities at the assignment's scope.

Scope is two-dimensional — tenant_id is mandatory, and an optional org_node_id narrows the grant to a subtree. A District Admin role assigned at a Swedish district OrgNode therefore yields competitions:* only for clubs and players in that subtree, while the same role assigned to a national admin yields it tenant-wide. Role inheritance lets templates extend each other (national-admin inherits regional-admin), keeping the predefined catalogue maintainable.

The petanque-specific catalogue ships with FIPJP Admin, Continental President, National Federation Admin, National Sports Director, District Admin, Club President/Secretary/Treasurer, Licensed Player, Umpire L1-L5, Tournament Director, Coach, Scorer/Volunteer and Spectator, each tuned to a realistic capability set. Sensitive-field restrictions add a column-level overlay — even a role with members:read may have date_of_birth or personal_id_number stripped from responses unless a more privileged capability is held. Temporary role grants attach a valid_from/valid_until window so a tournament director gets full event-management capabilities for one weekend only and is automatically removed afterwards.

Role request and approval workflows let users self-request (e.g. an aspiring umpire applying for L1 once certified), with the appropriate higher role acting as approver. Access debugging tools let administrators simulate "why was this request denied?" and trace the exact missing capability.