> ## Documentation Index
> Fetch the complete documentation index at: https://explore.airia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Roles

<Note>
  **Early Access:** Custom Roles is rolling out in stages. If **Settings → People & Access** does not yet show **Roles and Permissions**, contact your Airia representative for access. This page will be updated as Custom Roles becomes generally available.
</Note>

Custom Roles let you define your own roles with a hand-picked set of permissions, in addition to the Default Roles that ship with Airia. Use a custom role when none of the Default Roles match the access you want to grant — for example, a reviewer who can read agents and catalog content but cannot change platform settings. Custom roles can be assigned to users and groups just like Default Roles.

## Default vs custom roles

Two role types coexist in **Settings → People & Access → Roles and Permissions**:

* **Default Roles** ship with the product and cannot be edited or deleted. They cover the most common access patterns out of the box.
* **Custom Roles** are roles you define with your own name, description, and permission set. You can edit, duplicate, and delete them.

Both types appear in the same list and in role pickers throughout the product, tagged with a **Default Role** or **Custom Role** badge.

The Default Roles are:

| Role            | Description                                                                                              |
| --------------- | -------------------------------------------------------------------------------------------------------- |
| Platform Admin  | Full administrator with access to all settings, including account-level settings and platform operations |
| Admin           | Administrator with access to all settings except account-level settings                                  |
| Read-Only Admin | Administrator with read-only access                                                                      |
| Security Admin  | Administrator with credential management permissions                                                     |
| Project Admin   | Project-level administrator with write access to assigned projects only                                  |
| End User        | Standard user with basic access                                                                          |

## Create a custom role

<Steps>
  <Step title="Open Roles and Permissions">
    Go to **Settings → People & Access → Roles and Permissions**.
  </Step>

  <Step title="Click Add New Role">
    Select **Add New Role** in the top-right corner.
  </Step>

  <Step title="Name the role">
    Enter a **Role Name** (required). Add a **Description** to help other admins understand the role's purpose (optional).
  </Step>

  <Step title="Select permissions">
    Permissions are grouped by feature area (Budgets, Catalog, Common, Community, Gateway, Governance, Marketplace, MCP, Security, Settings, and Studio). Expand a group to choose individual permissions, or use the **Select all** checkbox next to a group to grant it in full. Most permissions offer **Manage** and **Read** levels, but some groups expose more granular levels — for example, **Budgets** uses project-scoped levels such as **Browse**, **Read All / Read Project / Read Self**, and **Update All / Update Project / Update Self**. Pick the least-privileged level that does the job, and use the search box to find a permission by name.

    A handful of permissions appear checked with a lock icon and can't be unchecked — every custom role needs them for the product's shared pages to load. See [Mandatory baseline permissions](#mandatory-baseline-permissions) below.
  </Step>

  <Step title="Save the role">
    Click **Create Role**. The role becomes available to assign immediately.
  </Step>
</Steps>

## Mandatory baseline permissions

A small set of permissions is automatically included in every custom role and can't be removed, regardless of what else the role grants. They're shown checked with a lock icon in the permission list. These cover pages the product loads unconditionally for every signed-in user (for example, tenant info and account settings) — without them, a role missing one would hit permission errors on ordinary navigation.

**Common → Roles → Read** is a related but separate case: it's *not* part of this mandatory set, so it stays a normal, freely toggleable checkbox. Granting it makes the role **admin-tier**, which changes the role's default landing page from the chat/catalog experience to the admin home page. Leave it unchecked to keep the role **end-user-tier** — this is the setting to use for a role that should only ever land users in chat or catalog, such as a narrow role scoped to a single feature area. The permission list flags this with an info icon next to **Common → Roles → Read**.

## Edit a custom role

<Steps>
  <Step title="Open the role's menu">
    On the Roles and Permissions list, click the **⋯** menu at the end of the custom role's row and choose **Edit Role**.
  </Step>

  <Step title="Update the role">
    Change the name, description, or permission selections.
  </Step>

  <Step title="Save your changes">
    Click **Save**. (Save stays disabled until you make a change.)
  </Step>
</Steps>

<Note>
  Editing a custom role updates the effective permissions of every user and group it's assigned to. Changes can take up to 5 minutes to apply to active sessions.
</Note>

## View a Default Role's permissions

You can't edit a Default Role, but you can open it to inspect its permission set in read-only mode. Click anywhere on a Default Role's row in the list — the role opens with its name, description, and permissions shown but disabled for editing. (A Default Role's **⋯** menu only offers **Duplicate Role**; there is no separate **View Role** action.) To build a role based on a Default Role's permissions, duplicate it instead (see below).

## Duplicate a role

Both Default and Custom Roles can be duplicated. Duplicating is the only way to base a new, editable role on a Default Role's permission set without selecting every permission by hand.

<Steps>
  <Step title="Open the role's menu">
    Click the **⋯** menu next to the role and choose **Duplicate Role**.
  </Step>

  <Step title="Edit the copy">
    The new role is named **Copy of \<original>** and opens in the editor pre-populated with the original's permissions. Rename it, adjust permissions, and click **Save**.
  </Step>
</Steps>

## Create a project-scoped role

A role created with **Add New Role** grants its permissions across all projects. To create a role whose access is limited to specific projects — like the built-in **Project Admin** — you must duplicate an existing project-scoped role rather than starting from scratch.

<Warning>
  There is no option to make a brand-new role project-scoped, and an all-projects role can't be converted into one. To create a project-scoped custom role, open the **⋯** menu on **Project Admin** (or another project-scoped role), choose **Duplicate Role**, then rename the copy and adjust its permissions — the duplicate stays project-scoped. When you assign it to a user or group, select the specific projects it applies to.
</Warning>

## Delete a custom role

A custom role can only be deleted when it is not assigned to any users or groups. Remove it from everyone first, then delete it.

<Steps>
  <Step title="Remove all assignments">
    Reassign the affected users and groups to another role, or remove this role from them, under **Settings → People & Access → People**. To see exactly who currently has the role, open the role and click **View people with this role**.
  </Step>

  <Step title="Open the role's menu">
    Click the **⋯** menu on the custom role's row and choose **Delete Role**.
  </Step>

  <Step title="Confirm">
    Confirm the deletion in the dialog.
  </Step>
</Steps>

<Warning>
  If the role is still assigned to any user or group, the deletion fails. Remove all assignments first. Default Roles cannot be deleted.
</Warning>

## Assign a custom role

Custom Roles are assigned exactly like Default Roles. Roles can be assigned to both **Users** and **Groups** under **Settings → People & Access → People** — see [User Management](/admin-hub/account_settings/user-management) for the invite and edit flows. When you assign roles, custom and default roles appear together in the same picker.

## Working with permissions

Permissions apply across all instances of a resource, not to a single item. They are organized into eleven feature-area groups; the largest are **Settings** (admin surfaces), **Studio** (agent authoring), and **Security** (guardrails, feeds, and integrations). Because the catalog grows with the product, use the in-product search rather than memorizing the full list.

For a full breakdown of what each permission controls, see the [Permissions Reference](/admin-hub/account_settings/permissions-reference).

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can I edit a Default Role?">
    No — Default Roles are immutable. Duplicate one to start from its permission set, then edit the copy.
  </Accordion>

  <Accordion title="Can a user have more than one role?">
    Yes. A user's effective permissions are the union of all roles assigned to them, plus any roles inherited from their groups.
  </Accordion>

  <Accordion title="Can I delete a role that's assigned to users?">
    No. A role must be removed from all users and groups before it can be deleted — otherwise the deletion fails. Reassign affected users to another role first.
  </Accordion>

  <Accordion title="Can I share, import, or export roles across accounts?">
    No. Custom roles can't be imported or exported, and they aren't shared across accounts. Each account defines its own custom roles independently. If you operate multiple accounts, recreate each custom role in every account where you need it.
  </Accordion>

  <Accordion title="How long until a role change takes effect?">
    Up to 5 minutes for active sessions.
  </Accordion>
</AccordionGroup>