Staff Assignments and Agency Roles
Who this is for
Agency account owners who need to add team members to the agency, assign them to client organisations, and configure what each staff member can see and do.
What you will complete
You will add a staff member to your agency account, assign them to one or more client organisations, and configure their agency role.
Before you begin
- You must be the agency account owner or have the
agency:managepermission. - The staff member must have an existing CloudAIPilot account with the email address you intend to invite.
Understanding agency staff roles
Agency Mode uses a separate role system from the standard org roles (Owner/Admin/Member/Viewer). Agency roles control what a staff member can do within the agency layer — not inside individual client orgs.
The system includes a built-in Agency Partner role with full agency access. You can also create custom roles with the exact permissions your team needs.
Available agency permissions:
| Permission | What it allows |
|---|---|
agency:read | View the agency dashboard, client list, and aggregated summaries |
agency:manage | Invite clients, configure branding, adjust quotas, manage agency settings |
client:read | View client org details, health scores, and resource summaries |
client:manage | Update client metadata, tags, SLA targets, and white-label overrides |
client:remove | Offboard a client org from the agency (destructive action) |
Add a staff member
Step 1 — Open Agency → Staff in the sidebar.
Step 2 — Click Add staff member.
Step 3 — Enter the staff member's email address.
Step 4 — Select or create their agency role.
- Choose Agency Partner to grant full access.
- Or select a custom role you've created.
Step 5 — Assign client organisations. By default, new staff are assigned to all clients. To restrict to specific clients, toggle Assign to specific clients only and select from the list.
Step 6 — Click Send invitation. The staff member receives an email invitation. Once accepted, they appear in your Staff list with status Active.
Edit staff client assignments
- Go to Agency → Staff.
- Click the staff member's name.
- Click Edit assignments.
- Add or remove client organisations from their assignment list.
- Click Save.
Changes take effect immediately. The staff member loses or gains visibility of the affected client orgs in their cross-org views.
Create a custom agency role
Step 1 — Go to Agency → Staff → Roles.
Step 2 — Click Create role.
Step 3 — Give the role a name (e.g. "Read-only analyst", "Client manager").
Step 4 — Toggle the permissions this role should have.
Step 5 — Click Save role.
The new role appears in the role selector when inviting or editing staff members.
Remove a staff member
- Go to Agency → Staff.
- Click the staff member.
- Click Remove from agency.
- Confirm the action.
The staff member immediately loses access to the agency dashboard and all client org views. Their account is not deleted — they retain access to any other CloudAIPilot orgs they belong to independently.
Common errors
Staff member invitation not received Cause: Email may be in spam, or the email address is not associated with a CloudAIPilot account. Fix: Ask them to check spam. If they don't have an account, they must create one first.
"Permission denied" updating staff assignments Cause: Your own agency role does not include agency:manage. Fix: Ask the agency account owner to update your role.
Staff member can see all clients but should only see some Cause: The assignment was set to "all clients" by default during invitation. Fix: Edit their assignment in Agency → Staff → [member] → Edit assignments.
Custom role not appearing in role selector Cause: The role may not have been saved correctly. Fix: Go to Agency → Staff → Roles to verify the role exists.