Create and use roles

Roles define what a workspace member or API token can do. Use them to keep workspace access scoped to the job: viewing dashboards, sending metrics, editing resources, managing tokens, or administering workspace resources.

A role is a named set of policy statements. Each statement has an effect, service, accessLevel, resourceType, and resourceId.

Default roles

Every workspace can use these built-in system roles:

• Admin has full workspace access. Its policy is ALLOW * * * *.
• ReadOnly can read and list workspace resources. Its policy allows Read and List operations on all services and resources.

System roles cannot be edited, renamed, or deleted. Custom role names also cannot start with #, because that prefix is reserved for internal roles.

Create a custom role in the UI

Open Roles from the main menu.

Use the Create role form:

1. Enter a role name, such as Metrics reader or Dashboard viewer.
2. Add an optional description.
3. Add one or more policy statements.
4. Select Create role.

Each policy statement has:

• Effect: choose ALLOW or DENY.
• Service: choose the API area, such as metrics, dashboards, alarms, or auth.
• Access level: choose an access level like Read, Write, List, Create, or Delete.
• Resource type: choose the type of resource, such as metric, dashboard, alarm, notification-channel, role, or token.
• Resource ID: enter one concrete resource ID or use * as a wildcard.

The service, access-level, and resource-type controls are backed by the backend authorization catalog. Use the search field in each dropdown to filter long lists.

Use * as a wildcard when the statement should match multiple services, access levels, resource types, or resource IDs.

Policy statements are evaluated in order. The last statement that matches a request determines whether it is allowed or denied. Put broad statements first and narrower exceptions later; a later matching ALLOW can override an earlier DENY, and a later matching DENY can override an earlier ALLOW.

Role creation and updates are permission bounded. A caller can only create or update a role when every ALLOW statement in the submitted role is already allowed by the caller's effective permissions. This prevents a delegated role manager from creating a broader role than they have themselves.

What policies can target

The role editor only shows workspace-specific policies. Account-specific policies are intentionally excluded from workspace roles because they depend on the signed-in account, not a workspace role.

Examples of account-specific actions that roles cannot grant:

• account profile and password changes;
• selecting or deleting account-owned workspaces;
• accepting workspace invitations;
• sending workspace invitations;
• removing workspace members.

Workspace invitations and member removal are owner-only account actions. They are not permissions that can be delegated through a workspace role or API token.

Use roles for invitations

Workspace invitations assign a role to the invited account.

To invite someone:

1. Open Workspaces.
2. Select the workspace you want to manage.
3. Use the Invite member form on the current workspace card.
4. Enter the person's email address.
5. Choose a role from the Role dropdown.
6. Select Send invite.

Only the workspace owner can send invitations. The role dropdown shows built-in roles and custom roles available to the workspace. Internal roles that start with # are hidden.

After the recipient accepts the invitation, the workspace appears on their Workspaces page with the assigned role.

The owner can later change an accepted member's role, or remove the member, from Members on the current workspace card.

Use roles for tokens

Every API token has a role. See Create an API token for the token creation flow and API example.

Creating a token is also permission bounded. The caller must be allowed to create tokens, read the selected role, and hold every allowed permission in that role. For example, a role that can create tokens and read the Admin role still cannot mint an Admin token unless it already has the permissions granted by Admin.

Practical workflow

Start with ReadOnly for people who only need to inspect dashboards and metrics. Use Admin only for trusted accounts that need broad workspace control.

Create custom roles when a person or token needs a narrower policy than the default roles provide. Typical examples are separate roles for dashboard viewers, metric writers, alert managers, and import jobs.