Roles & Permissions

Miranda uses a two-tier permission system: a legacy UserRole enum on the User model for base access level, and a foundation-scoped Role model with granular permissions for fine-grained control.

Legacy UserRole enum

Every User record has a role field using the UserRole enum:

Value	Description
owner	Full access — billing, account deletion, team management. Bypasses all permission checks.
admin	Full operational access, cannot manage billing or delete the foundation
member	Access governed by their assigned Role model and its permissions array
readonly	View-only access across the foundation

The legacy enum is being superseded by the Role model but remains on all User records for backward compatibility.

Role model (new system)

Foundations define custom roles via the Role model. Each role is scoped to a foundation and contains:

Field	Type	Description
name	string	Display name (e.g., “Program Director”)
slug	string	URL-safe identifier. The owner slug has special meaning — it bypasses all checks
permissions	array	List of permission keys granted to this role
is_default	boolean	Whether this is a system-seeded role
sort_order	integer	Display ordering

Default role seeding

When a foundation’s roles are first accessed (via GET /api/team/roles), Miranda seeds default roles based on the foundation’s org_type from config/org-types.php. The Owner role is always created first with an empty permissions array (owners bypass all checks).

// The Owner role always bypasses permission checks
if ($user->teamRole->slug === 'owner') {
    return true;
}

Assigning roles to users

Users are assigned a role via the role_id foreign key on the User model. When a user is invited, they receive the role specified in the invitation.

Permission keys

Permissions are defined in config/permissions.php and organized into groups:

People

Key	Description
contacts.view	View contacts
contacts.create	Create contacts
contacts.edit	Edit contacts
contacts.delete	Delete contacts

Donations

Key	Description
donations.view	View donations
donations.create	Record donations
donation_pages.view	View donation pages
donation_pages.create	Create donation pages
donation_pages.edit	Edit donation pages

Communications

Key	Description
campaigns.view	View campaigns
campaigns.create	Create campaigns
campaigns.edit	Edit campaigns
campaigns.send	Send campaigns
sequences.view	View sequences
sequences.create	Create sequences
sequences.edit	Edit sequences

Programs

Key	Description
scholarships.view	View scholarships
scholarships.create	Create scholarships
scholarships.review	Review applications

Tools

Key	Description
import.use	Import data

Administration

Key	Description
settings.view	View settings
settings.edit	Edit settings
billing.manage	Manage billing
team.view	View team members
team.invite	Invite team members
team.remove	Remove team members

RolePermissionService

The RolePermissionService handles all permission checks:

class RolePermissionService
{
    public function can(User $user, string $permission): bool
    {
        // New Role system: check role_id -> teamRole -> permissions array
        if ($user->role_id && $user->teamRole) {
            if ($user->teamRole->slug === 'owner') {
                return true; // Owner bypasses all checks
            }
            return in_array($permission, $user->teamRole->permissions ?? [], true);
        }

        // Legacy: Owner enum always has access
        if ($user->role === UserRole::Owner) {
            return true;
        }

        return false;
    }

    public function allPermissionKeys(): array
    {
        // Collects every permission key from config/permissions.php
    }
}

Team invitations

New team members are invited via the TeamInvite model:

Field	Description
email	Invitee’s email address
role_id	The Role to assign when accepted
token	64-character random token (serves as invite URL auth)
expires_at	Invitation expiry (7 days from creation)
accepted_at	Null until accepted

Invite flow

1. Owner calls POST /api/team/invite with email and role_id
2. Miranda creates a Supabase account for the invitee (or updates their password if existing)
3. A TeamInviteMail is sent with a join link containing the token and a temporary passphrase
4. Invitee clicks the link and calls POST /api/team/invites/{token}/accept or POST /api/team/invites/{token}/accept-and-login
5. A User record is created in the foundation with the specified role

Guardrails

• Cannot invite someone who is already a team member
• Cannot send a duplicate invite to the same email while one is pending
• Cannot modify or delete the owner role
• Cannot change an owner’s role or remove an owner
• Cannot remove yourself from the team
• Deleting a role unassigns all users from it (sets role_id to null)

API endpoints

Method	Path	Description
GET	/api/team	List team members and pending invites
GET	/api/team/roles	List foundation roles (seeds defaults if empty)
POST	/api/team/roles	Create a custom role
PUT	/api/team/roles/{role}	Update role name and permissions
DELETE	/api/team/roles/{role}	Delete a role
POST	/api/team/invite	Send a team invitation
DELETE	/api/team/invites/{invite}	Cancel a pending invite
PUT	/api/team/members/{user}/role	Change a member’s role
DELETE	/api/team/members/{user}	Remove a team member
GET	/api/team/permissions	List all permission groups and keys