Assign and change roles

Last updated: May 19, 2026

Assign and change roles

Open Settings → Team → People, find the member, click the action menu (three dots) → Change role → pick the new role → confirm. The change is immediate and recorded in the audit log. Roles are per-workspace — the same user can be Owner here and Viewer elsewhere.

Who is this for

Admins promoting a teammate, demoting a former contractor, or restructuring after a reorg.

Before you start

  • You need a role with team-write access: admin, owner, or super_admin

  • Be confident in the target role — see full roles reference

  • The change takes effect immediately on their next page navigation — coordinate with them if it's a sensitive transition

How to change a role

Step 1: Open People page

Navigate to Settings → Team → People. Find the member's row (search by name or email if needed).

Step 2: Open action menu

Click the three-dot icon at the right of the row. The menu opens with options including Change role.

Step 3: Pick the new role

A modal opens with:

  • Current role: their existing role with power level

  • New role: dropdown of valid choices

  • Effect summary: bullet list of what they gain or lose

The dropdown excludes roles you can't grant (e.g. you can't grant super_admin unless you're already super_admin).

Step 4: Confirm

Click Confirm role change. Backend updates team_membership.role and creates an audit log entry (action: role_change, metadata: { old_role, new_role }).

Step 5: They see the change

The next time they navigate in the app, their UI re-renders with the new permissions. If they were viewing something they no longer have access to, a toast appears: "Permission changed — refresh" and the page reloads.

Role hierarchy reminder

super_admin (100)  ────  Org-wide, set at Organization level (not workspace)
        ↓
admin       (90)   ──┐
                     │ Per workspace
owner       (80)   ──┤ (one user can hold different roles in different workspaces)
                     │
manager     (70)   ──┤
                     │
mediabuyer  (60)   ──┤
                     │
finance     (50)   ──┤
                     │
viewer      (40)   ──┘

Anyone with admin (90) or higher can manage roles within their workspace. super_admin can manage roles across all workspaces in the Org.

Promoting to owner

Owner is the only role that holds billing rights within a workspace. Many workspaces have just one owner (the founder or finance lead). Multiple owners = shared billing access.

If you want to transfer workspace ownership (one owner replacing another), use the dedicated flow: transfer workspace ownership — it's a different operation with extra safeguards (cannot leave a workspace without an owner).

If you want to add an owner alongside existing one(s), use the regular Change role flow. The number of owners isn't capped.

Demoting an owner

The same Change role flow. Constraint: at least one owner must remain per workspace. If you try to demote the last owner, the backend blocks with: "Cannot leave workspace without an owner".

To replace the only owner: first promote someone else to owner, then demote the original.

Cross-role audit trail

Every role change is recorded in the audit log:

{
  "action": "role_change",
  "user_id": "<who-was-changed>",
  "owner_id": "<workspace-owner>",
  "metadata": {
    "old_role": "viewer",
    "new_role": "mediabuyer",
    "changed_by": "<admin-user-id>"
  },
  "ip_address": "...",
  "created_at": "2026-05-17T..."
}

View at Settings → Team → Audit Log (filter by action: role_change). See audit log article for the full schema and filters.

Bulk role changes

The People page supports bulk selection: tick multiple rows → toolbar shows actions → Change role → apply same new role to all selected.

Useful for offboarding waves or onboarding a class of new contractors with the same role.

What you'll see

After a successful role change:

  • The role column on the row updates immediately (e.g. viewer → mediabuyer)

  • A toast: "Role updated"

  • An audit log entry visible at /settings/team/audit-log

  • The affected user sees a permission-changed toast on their next navigation

Common issues

  • Dropdown grey on the role you want to grant: you don't have permission to grant that role. Only admin/owner can promote within workspace; only super_admin can grant super_admin.

  • "At least one owner required": you tried to demote the last owner. Promote someone else first, then demote.

  • User still seeing old permissions after change: they need to refresh or navigate to a new page. The change is server-side immediate, but the React app caches some checks until next navigation.

  • Error: "Insufficient permissions": your role lacks team-write. Ask an admin or owner to make the change.

  • Cannot change own role: by design (prevents self-locking). Ask another admin to change yours.

Permission re-evaluation timing

Backend permission checks happen on every API request. Frontend permission checks (button enable/disable, sidebar items visibility) happen on:

  • Initial page load (cached)

  • Route change (recomputed)

  • Force refresh (Cmd+Shift+R)

So a fresh role takes effect on next page load. There's no "kick out" — if the user is mid-edit on something they no longer have access to, they get a friendly toast and a redirect.

Related