Custom Roles

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

Custom roles are zero-touch: existing admins and members keep working exactly as before. Custom roles apply only where you explicitly assign them.

Overview

• Who this is for: Enterprise organizations that need finer control than admin vs member. For example: a Support Agent who can improve answers but can't delete sources, or a Billing Admin who can manage invoices but can't see chatlogs.
• What you get: A 14-area matrix covering agents, sources, actions, channels, contacts, analytics, activity, API keys, webhooks, members, billing, workspace settings, audit logs, and roles themselves.
• Plan requirement: Custom Roles are part of the Enterprise plan. See the Enterprise gating section for what happens if the plan lapses.
• Audit-friendly: Every create, update, delete, assign, and unassign is written 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 14 areas.

Roles management itself is intentionally narrow: a custom role can grant view on the Roles area so a member can see which roles exist, but creating, editing, and deleting custom roles is permanently owner-only.

Action hierarchy

To keep matrices sane, several actions imply lower actions:

• edit implies view
• delete implies edit implies view
• export implies view
• manage implies view

The Roles editor enforces this 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 any action that depends on it. Removing view from Contacts also removes edit, delete, and export.

This means you can never end up with edit permission but no view, or manage billing but no view billing. Saved matrices are always consistent.

Creating a role

Navigate to Settings → Roles and click New role. You'll be asked for a name, a description, and a permission matrix.

Four scaffolds are available as starting points. Pick whichever is closest to what you need, then tweak the matrix.

Analytics Viewer

Read-only across the product. Useful for stakeholders who need to see what's happening but should never 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. Can add, edit, delete, and retrain sources, but can't touch agents themselves beyond reading them.

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

Support Agent

A frontline operator. Can review chatlogs, improve agent answers, and manage contact records — but 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 exactly the actions you want.

Naming rules

• Name: 2–50 characters, case-insensitive unique per organization.
• Description: optional, up to 200 characters.
• The names owner, admin, and member are reserved and rejected.

Assigning roles to members

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

• Existing members keep their current role until you change it. Creating a new custom role does not silently re-assign anyone.
• You can also unassign a custom role at any time — the member reverts to their 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 org, use the existing transfer-ownership flow.
• The last owner is protected. You cannot remove or demote the last remaining owner — the dialog blocks it.

Enterprise gating

Custom Roles require the Enterprise plan. The behavior when the plan lapses is intentionally conservative:

• Existing custom roles keep enforcing. We never silently grant privileges back to a member by ignoring their custom role. Permission checks continue to run.
• All mutations are blocked. Create, update, delete, assign, and unassign all return a "Re-upgrade to Enterprise" error from both the dashboard and the REST API.
• The Roles page shows a banner. Write controls are disabled.
• The Change Role dialog disables the custom-role selector. Members can still be moved between built-in roles, but custom roles cannot be assigned or removed.

Re-upgrading to Enterprise restores full read/write immediately. No data is lost during a lapse.

FAQ

Can I assign Owner as a custom role?

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

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

Nothing. Custom roles apply only where you explicitly 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 deleting it. This prevents a member from being silently re-mapped to a built-in role you didn't intend.

What happens if my Enterprise plan lapses?

Existing assignments keep enforcing permissions exactly as they did before. All custom-role mutations (create, update, delete, assign, unassign) are blocked with a "Re-upgrade to Enterprise" error until you re-upgrade. See Enterprise gating.

Does this apply to API keys?

Not yet. Today, custom roles apply to members (real users). Per-API-key custom role assignment is on the Phase 3 roadmap, so API keys currently continue to 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, which you can pipe to a file for backup or to replay against another environment.

Are role changes audited?

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

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 org:

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.