Docs
Browse the docs

Team roles and permissions

See what each built-in role (Owner, Admin, Editor, Analyst, Viewer, Billing) can do, how custom roles work on Business, and how API tokens narrow access.

View as Markdown

Access is built from permissions. A role is a set of permissions, and every API operation and MCP tool declares the one permission it needs.

Permission matrix#

This table is generated from the code that enforces it.

Permission Allows Owner Admin Editor Analyst Viewer Billing
analytics.read View dashboards, stats, live data and reports ✓ ✓ ✓ ✓ ✓ -
analytics.export Create exports and download data ✓ ✓ ✓ ✓ - -
content.write Manage goals, funnels, segments, notes, alerts, email reports, links and dashboards ✓ ✓ ✓ ✓ - -
sites.manage Create sites and change site settings, tracking, privacy, traffic rules, integrations and sharing ✓ ✓ ✓ - - -
uptime.manage Manage uptime checks and status pages ✓ ✓ ✓ - - -
members.manage Invite members and change roles and site access ✓ ✓ - - - -
tokens.manage Create and revoke API tokens for anyone in the workspace (members can always manage their own) ✓ ✓ - - - -
billing.manage Change plan, payment details and view invoices ✓ ✓ - - - ✓
workspace.manage Workspace settings, security, SSO, webhooks, white label, audit log and deletion ✓ ✓ - - - -

A member with no access to a site can't see it anywhere, including in lists, exports and the API.

Testimonials adds no permission of its own. Reading them is analytics.read, exporting them is analytics.export, the daily work (approving, tagging, forms, widgets, requests, imports) is content.write, and settings and permanent deletion are sites.manage. The email of a person who gave a testimonial is shown only to members with content.write.

Built-in roles#

  • Owner: every permission. Each workspace has exactly one owner. Only the owner can transfer ownership, and the owner can't be removed or given another role. The owner can always log in with a password or a passkey, whatever the workspace's login rules say.
  • Admin: every permission, the same as the owner.
  • Editor: analytics, exports, content (goals, funnels, segments, notes, alerts, email reports, links and dashboards), sites and site settings, uptime checks and status pages. No members, billing, tokens for others or workspace settings.
  • Analyst: analytics, exports and content. No site settings or uptime.
  • Viewer: read-only analytics.
  • Billing: plan, payment details and invoices only. No analytics.

Every built-in role is available on every plan. A member has one role, plus access to all sites or to selected sites. The role decides what they can do, and the site access decides where.

Nobody can hand out more than they hold: you can only give a role when you hold every permission in it, and you can only change or remove a member whose permissions and sites are within your own.

Custom roles#

On Business, Workspace settings → Roles shows what each role can do and lets members with members.manage create custom roles. Choose New role, then:

Field What it does
Name (name) Shown wherever roles are listed. Up to 60 characters, unique in the workspace.
Permissions (permissions) Any combination of the nine permissions in the matrix above. You can only tick permissions you hold yourself.

Assign a custom role like a built-in one, when inviting or editing a member. Editing a custom role changes what every member who holds it can do. A role that members still hold can't be deleted. Deleting a role also deletes pending invitations that use it.

Over the API, roles are at /workspaces/<workspace id>/roles and the MCP tools are roles_list, roles_create, roles_update and roles_delete. Over MCP only roles_list runs. The others return a link to the roles page, see Actions for a person. To give a member a custom role, send role as custom with the role's id in custom_role_id.

API tokens narrow, never widen#

An API token belongs to a member. Its effective access is:

  • permissions = the member's role ∩ the permissions chosen for the token,
  • sites = the member's sites ∩ the sites chosen for the token.

If the member's role or site access shrinks, their tokens shrink with it. Members can always manage their own tokens, and tokens.manage lets admins manage everyone's.