Skip to main content
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.
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:

​
Create a custom role

1

Open Roles and Permissions

Go to Settings → People & Access → Roles and Permissions.
2

Click Add New Role

Select Add New Role in the top-right corner.
3

Name the role

Enter a Role Name (required). Add a Description to help other admins understand the role’s purpose (optional).
4

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 below.
5

Save the role

Click Create Role. The role becomes available to assign immediately.

​
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 handled automatically based on the role’s tier, so you don’t toggle it yourself:
  • A role that grants any admin-level permission — anything beyond the end-user baseline, such as managing agents, gateways, or account settings — is treated as admin-tier. Airia automatically adds Roles → Read and locks it (checked, can’t be unchecked): admin-tier roles land on the admin home page, and the admin shell needs this permission to load correctly.
  • A role that grants only end-user-level permissions stays end-user-tier. Roles → Read is not added, and its users land in the chat/catalog experience — this is the right setup for a narrow role scoped to a single feature area.
The role’s tier, and therefore its default landing page, follows the permissions you select; you never set it by hand. The permission list shows an info note explaining this next to Common → Roles → Read. (Note: to create an admin-tier role you must hold Roles → Read yourself.)

​
Edit a custom role

1

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.
2

Update the role

Change the name, description, or permission selections.
3

Save your changes

Click Save. (Save stays disabled until you make a change.)
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.

​
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.
1

Open the role's menu

Click the ⋯ menu next to the role and choose Duplicate Role.
2

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.

​
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.
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.

​
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.
1

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.
2

Open the role's menu

Click the ⋯ menu on the custom role’s row and choose Delete Role.
3

Confirm

Confirm the deletion in the dialog.
If the role is still assigned to any user or group, the deletion fails. Remove all assignments first. Default Roles cannot be deleted.

​
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 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.

​
Frequently asked questions

No — Default Roles are immutable. Duplicate one to start from its permission set, then edit the copy.
Yes. A user’s effective permissions are the union of all roles assigned to them, plus any roles inherited from their groups.
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.
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.
Up to 5 minutes for active sessions.