---
id: UJ-011
title: Manage team members, roles, and approvals
actors: [OWNER, ADMIN]
surface: app.zync.is/settings/users and app.zync.is/settings/roles
goal: Give the right people the minimum tenant access needed for their work.
trigger: Admin opens team or role settings.
preconditions:
  - Active OWNER/ADMIN session with membership-management permission.
success_state: Invitation, role, approval, freeze, or custom-role change is persisted and audited.
source_specs:
  - docs/specs/2026-05-31-team-users-settings.md
  - docs/specs/2026-06-01-settings-roles.md
  - docs/specs/2026-05-31-field-level-permissions.md
  - docs/specs/2026-05-31-staff-portal-detail.md
---

## Happy path

1. Admin opens team settings → sees active, pending, frozen, and invited memberships.
2. Admin invites a person by email and selects a built-in or custom role → Zync sends the invitation and records it as pending.
3. Invitee accepts through UJ-003 → membership becomes active immediately or waits for approval according to tenant policy.
4. Admin approves, changes role, freezes, unfreezes, or revokes access → Zync updates membership, invalidates stale authorization, and records the audit event.
5. Admin creates/edits a custom role → selects module/field permissions and saves; deleting an assigned role requires a replacement role.

## Alternate and failure paths

- Duplicate/pending invitation → show existing state and allow resend/revoke according to permission.
- Approval denied or invitation expired → no active membership is created.
- Attempt to remove the last OWNER, self-demote, or change protected role → block with a confirmation/error.

## Permissions and boundaries

- OWNER has full membership/role control; ADMIN is restricted by billing and deletion rules.
- UI visibility is not authorization; every mutation rechecks permission server-side.

## Source specs

- `docs/specs/2026-05-31-team-users-settings.md`
- `docs/specs/2026-06-01-settings-roles.md`
- `docs/specs/2026-05-31-field-level-permissions.md`
- `docs/specs/2026-05-31-staff-portal-detail.md`