Custom Roles

Custom Roles let Enterprise organizations move beyond the built-in owner, admin, and member roles. You define a role once, with a name, a description, and a checked permission matrix across 17 areas. Then you assign the role to any member. When a member has a custom role, the custom role overrides the built-in role for every permission check.

Custom roles change nothing by default. Existing admins and members keep working as before. Custom roles apply only where you assign them.

Overview

• Who this is for: Enterprise organizations that need finer control than the built-in admin and member roles. For example, a Support Agent can improve answers but cannot delete sources. A Billing Admin can manage invoices but cannot see chatlogs.
• What you get: A 17-area matrix covering the whole product. Areas include agents, sources, actions, channels, contacts, analytics, activity, API keys, webhooks, members, billing, workspace settings, audit logs, roles, Inbox, Teams, and Help Center.
• Plan requirement: Custom Roles are part of the Enterprise plan. If the plan lapses, see Enterprise gating for what happens.
• Audit trail: Every create, update, delete, assign, and unassign action writes to the audit log with a full before/after permissions diff.

Permission matrix reference

A custom role is a checked subset of the following actions across 17 areas.

Roles management stays narrow by design. A custom role can grant view on the Roles area, so a member can see which roles exist. Creating, editing, and deleting custom roles is always owner-only.

Inbox, Teams, and Help Center actions are flat: granting one action does not grant any other. For example, you can grant read-only Inbox access without also granting write access.

Action hierarchy

To keep matrices simple, several actions imply lower actions:

• edit implies view
• delete implies archive and edit, which implies view
• export implies view
• manage implies view

Inbox, Teams, and Help Center actions do not follow this hierarchy. See the section above.

The Roles editor enforces this hierarchy for you:

• Checking a higher action auto-checks every action it implies. Toggling delete on Sources also enables edit and view on Sources.
• Unchecking a lower action auto-disables every action that depends on it. Removing view from Contacts also removes edit, delete, and export.

As a result, a saved matrix never has edit without view, or manage for billing without view for billing. Saved matrices are always consistent.

Creating a role

Go to Settings → Roles and click New role. Enter a name, a description, and a permission matrix.

Four scaffolds are available as starting points. Pick the scaffold closest to your needs, then adjust the matrix.

Analytics Viewer

Read-only access across the product. Useful for stakeholders who need visibility into activity but must not change anything.

• Agents: view
• Sources: view
• Contacts: view
• Channels: view
• Analytics: view, export
• Activity: view
• Audit Logs: view
• Everything else: none

Source Manager

Owns the knowledge base. This role can add, edit, delete, and retrain sources, but cannot change agents beyond viewing them.

• Sources: view, create, edit, delete, retrain
• Agents: view
• Everything else: none

Support Agent

Handles day-to-day support work. This role can review chatlogs, improve agent answers, and manage contact records. It cannot delete anything or change settings.

• Agents: view, improve_answers
• Activity: view
• Contacts: view, edit
• Everything else: none

Billing Admin

Manages invoices and credits without seeing customer data.

• Billing: view, manage
• Members: view
• Everything else: none

You can also start from a blank matrix and check only the actions you want.

Naming rules

• Name: 2–50 characters. Must be unique per organization (not case-sensitive).
• Description: optional, up to 200 characters.
• The names owner, admin, and member are reserved. You cannot use them.

Assigning roles to members

Open Settings → Members, find the member, and click Change role. The dialog lets you pick a built-in role or any custom role you have defined.

• Existing members keep their current role until you change it. Creating a new custom role does not automatically reassign anyone.
• You can also unassign a custom role at any time. The member then reverts to the built-in role.
• Owner is never a custom role. Custom roles are always assigned on top of admin or member. To change who owns the organization, use the transfer-ownership flow.
• The last owner is protected. You cannot remove or demote the last remaining owner. The dialog blocks the action.

Enterprise gating

Custom Roles require the Enterprise plan. When the plan lapses, the product behaves conservatively:

• Existing custom roles keep enforcing. The system never grants privileges back to a member by ignoring the custom role. Permission checks continue to run.
• Create, update, delete, and assign are blocked. Both the dashboard and the REST API return a "Re-upgrade to Enterprise" error.
• Unassign stays available. You can still remove a member's custom role while the plan is lapsed. This lets you clean up assignments and move members back to a built-in role.
• The Roles page shows a banner. Write controls other than unassign are disabled.
• The Change Role dialog disables new custom-role assignment. You can still move members between built-in roles and remove an existing custom-role assignment.

When you re-upgrade to Enterprise, full read and write access returns immediately. No data is lost during a lapse.

FAQ

Can I assign Owner as a custom role?

No. Ownership is a special organization-level relationship, not a permission matrix. Use the transfer-ownership flow to change owners.

What happens to existing members when I create a custom role?

Nothing. Custom roles apply only where you assign them. Existing admins and members keep their built-in roles until you change them.

Can I delete a role that has assignees?

No. You must reassign every member off the role before you delete it. This stops a member from moving unexpectedly to a built-in role you did not intend.

What happens if my Enterprise plan lapses?

Existing assignments keep enforcing permissions as before. Create, update, delete, and assign are blocked with a "Re-upgrade to Enterprise" error until you re-upgrade. Unassign remains available, so you can still clean up assignments. See Enterprise gating.

Does this apply to API keys?

Not yet. Today, custom roles apply only to members (real users). Per-API-key custom role assignment is on the Phase 3 roadmap. Until then, API keys use the existing read/write scopes.

Can I export role definitions?

Yes. Use the REST API. GET /v1/roles returns the full set of custom roles with their permission matrices. You can pipe the output to a file for backup, or replay it against another environment.

Are role changes audited?

Yes. Every create, update, delete, assign, and unassign action writes an audit log entry. Edits include a full before/after permissions diff, so you can see which actions changed.

REST API quickref

All custom-role endpoints live under /v1/roles and /v1/members/:userId/custom-role. Reads require the read scope. Writes require the write scope and are owner-only.

Example: list every custom role in your organization.

curl https://www.agentstack.build/api/v1/roles \
  -H "Authorization: Bearer $AGENTSTACK_API_KEY" \
  -H "x-organization-id: $ORG_ID"

The full OpenAPI spec is auto-generated and available at /api/v1/openapi.json.