# Create and use roles

Understand default roles, custom role policies, invitations, and token permissions.

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](/docs/tokens) 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.