> For the complete documentation index, see [llms.txt](https://docs.digitalapi.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.digitalapi.ai/api-gateway/setup/defining-roles-and-permissions.md).

# Defining roles and permissions

A **role** bundles permissions. Each permission is a verb on a resource type, expressed as `<resource>.<verb>` (for example, `api.create`, `role.update`, or `service.delete`). Roles assign to users or groups, and a user's effective permissions are the union of every role they hold plus every role on every group they belong to. AILIX ships built-in roles such as Org Admin and Read-only; custom roles cover everything else.

### Creating a role

#### Create a custom role

**Before you start**

* The role's intent in one sentence. *Read-only access to analytics and traces* is sharp; *general user* is not.
* The permission set. Permissions group by resource type (APIs, Custom analytics, Revisions, Products, Plugins, Upstreams, Environments, Developers, Apps, Users, Groups, Roles, Authentication, and others). Each resource type has between three and seven verbs (Create, Delete, Force delete, Import, List, View, Edit, plus type-specific verbs such as `revision.deploy`).
* The `role.create` permission. If **Create role** is disabled, your role lacks the permission.

To create a role:

1. From the left sidebar, choose **Setup** → **Roles** → **Create role**. The portal opens the **Create role** modal.
2. Enter a **Display Name** (required), a **Name** (the slug, required and permanent), and an optional **Description**.
3. Use **Search permissions** to find permissions by name, or expand resource sections.
4. Tick the verbs to grant. Each section header reads `<resource> <selected>/<total>` (for example, `APIs 0/7`); click to expand or collapse.
5. Use **Select all** or **Clear** within a resource section to grant or revoke every verb on that resource at once.
6. Click **Create role**.

![Figure 17-1. The Create role dialog.](/files/l5Tj8QZTDEzdfBb5qgiP)

The numbered callouts in Figure 17-1 are:

1. **Display Name.** Operator-facing label. Required.
2. **Name.** Permanent slug. Required.
3. **Description.** Optional intent.
4. **Search permissions.** Live filter across the permission list.
5. Resource section headers (such as `APIs 0/7`). Show selected versus total per resource.
6. Permission checkboxes. Format `<verb>` over `<resource>.<verb>`.
7. **Select all** and **Clear.** Per-resource bulk actions.
8. **Cancel** and **Create role.** Modal actions.

**Verify**

1. The modal closes and the role appears at the top of the **Roles** list.
2. The **PERMISSIONS** column reads the count of ticked verbs.

{% hint style="success" %}
**Result:** The custom role exists. Assign it from the role's detail page, or from a user's or group's detail page.
{% endhint %}

{% hint style="danger" %}
**Caution:** Two permission combinations deserve segregation:

* `role.create` plus `role.update` together let a holder grant themselves any permission. Reserve this combination for a small group of trusted admins.
* `<resource>.force-delete` permissions (`api.force-delete`, `revision.force-delete`, and similar) bypass safety checks that the regular `<resource>.delete` honours. Reserve them for incident response rather than steady-state work.
  {% endhint %}

{% hint style="info" %}
**Note:** A new role does not appear in the assignment dropdowns on **Users** or **Groups** until those pages are refreshed. After creating a role, hard-refresh (⌘-Shift-R or Ctrl-Shift-R) before searching for it on the assignment side.
{% endhint %}

{% hint style="success" %}
**Tip:** Build roles incrementally. Save with the obvious permissions, assign the role to a test user, see what they can and cannot do, then edit the role to add what is missing. Trying to enumerate every permission upfront produces role bloat; most roles need fewer permissions than they grow into.
{% endhint %}

Related tasks:

* [Working with groups](/api-gateway/setup/working-with-groups.md#working-with-groups): assign the role to a group rather than to individual users.
* [Inviting and managing users](/api-gateway/setup/inviting-and-managing-users.md#inviting-and-managing-users): assign the role directly to one user.

### Reading the roles list

#### Browse and filter roles

To browse:

1. From the left sidebar, choose **Setup** → **Roles** (`/organization/roles`).
2. Filter with **Search roles...**; click **All roles** to widen the view after a filter.

![Figure 17-2. The Roles list.](/files/b753PWBPUQevepV3vbec)

Table 17-A. Columns on the Roles list.

| Column          | What it shows                 |
| --------------- | ----------------------------- |
| **Name**        | Display name.                 |
| **TYPE**        | Built-in or custom.           |
| **PERMISSIONS** | Count of permissions granted. |

**Verify**

1. The URL is `<your-helix-portal-domain>/organization/roles`.
2. **Create role** is visible at the top right.

{% hint style="success" %}
**Result:** A role inventory, two clicks from any role.
{% endhint %}

Related tasks:

* [Create a custom role](#create-a-custom-role): author a new role.
* [Working with groups](/api-gateway/setup/working-with-groups.md#working-with-groups): assign roles via groups for scale.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.digitalapi.ai/api-gateway/setup/defining-roles-and-permissions.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.