# Roles

Learn about roles, which grant users permissions in an application.

> For the index of this section of the site, see [llms.txt](https://fusionauth.io/docs/llms.txt)

Roles in FusionAuth are associated with an [application](https://fusionauth.io/docs/concepts/types/applications.md). You can define as many roles as you want in an application. There are no limits on the number of roles a user or a group can have.

Roles are application specific and may be specific to the domain of the application. Roles are typically used by APIs and applications to control access to functionality. For example, Zendesk presents a different user interface to users with the `agent` role than to users without that role.

For a further example, an e-commerce application may have the following roles:

*   `admin`
*   `seller`
*   `shopper`

On the other hand, a content management system may have these roles:

*   `admin`
*   `editor`
*   `contributor`
*   `subscriber`

Roles are available in the [JWT](https://fusionauth.io/docs/authentication/oauth/tokens.md) upon successful [authorization](https://fusionauth.io/docs/concepts/authentication-authorization.md) and are also returned as part of the [user's registrations](https://fusionauth.io/docs/apis/registrations.md).

You can associate roles with [users](https://fusionauth.io/docs/concepts/types/users.md) directly via their [registration](https://fusionauth.io/docs/concepts/types/registrations.md). Or you can assign an application role to a [group](https://fusionauth.io/docs/concepts/types/groups.md), and then any users in that group who have access to that application will have that role.

## Core Concepts Relationships

Below is a visual reminder of the relationships between FusionAuth's primary core concepts.

![Diagram showing Roles used within FusionAuth](https://fusionauth.io/img/docs/get-started/core-concepts/core-concepts-relationships-roles.png)

## Role Attributes

Roles in FusionAuth have the following attributes:

`Name`

*   Required

The name of the role. This value should be short and descriptive. Roles can only be created and deleted, only the role description may be modified.

`Default`

*   Optional

One or more roles may be marked as default. A default role will be automatically added to new user registrations when no roles are explicitly provided on the API request.

`Super Role`

*   Optional

A role may be optionally marked as a super user role. This indicator is just a marker to indicate to you that this role encompasses all other roles. It has no effect on the usage of the role.

`Description`

*   Optional

An optional description to better describe the intended use of this role.

## Check Roles in Your App

When a user logs into an application, FusionAuth adds the user's roles for that application to the `roles` claim of the [access token](https://fusionauth.io/docs/authentication/oauth/tokens.md#access-token). Your app reads the roles from the token and decides what the user can do. Check the roles on every protected route, before the route does any work.

The following function from an [example app](https://github.com/FusionAuth/fusionauth-example-get-started) validates the access token, then checks whether the user has at least one of the allowed roles:

```typescript
async userHasAccess(req: Request, res: Response, roles: Array<string>): Promise<boolean> {
  const jwt = await this.getUser(req, res);

  // @ts-ignore
  if (!jwt || !jwt.roles || jwt.roles.length === 0) {
    return false;
  }

  // @ts-ignore
  return jwt.roles.some(role => roles.includes(role));
}
```

A route passes the roles that may access the route. The `/admin` route only allows the `admin` role, and redirects other users:

```typescript
app.get("/admin", async (req, res) => {
  if (!await sdk.userHasAccess(req, res, ["admin"])) {
    res.redirect(302, '/account');
    return;
  }

  res.sendFile(path.join(__dirname, '../templates/admin.html'));
});
```

Many frameworks include security libraries that perform the same check. To learn how to validate the access token itself, see [Validate an Access Token](https://fusionauth.io/docs/authentication/oauth/tokens.md#validate-an-access-token).

## FusionAuth Admin UI Roles

FusionAuth provides the Admin UI for the running instance with several built-in roles. These can be assigned to any user registered with the FusionAuth admin application. These roles control access to functionality within the FusionAuth Admin UI.

Note

These roles are used only internally to manage authorization within the FusionAuth Admin UI application.

These roles are *not global* and are not present in any other applications for which FusionAuth provides authentication, authorization, or user management.

Below you can see a user's registration in the FusionAuth application, with their assigned admin role.

![FusionAuth application roles](https://fusionauth.io/img/docs/screenshots/user-admin-role.png)

### Role Schema and Exceptions

The table below outlines how Admin UI roles were designed at an abstract level. Of course, risk is always relative to the information and organization; even a low-access role can do significant damage in the wrong hands.

In general, FusionAuth roles follow this convention:

| Suffix | Access Level | Meaning |
| --- | --- | --- |
| `_viewer` | low | Can view entities of a particular type |
| `_manager` | high | Can add or edit the entities |
| `_deleter` | high | Can delete entities |

However, when an entity is missing one of these roles, such as a `_deleter` role, the `_manager` role has additional capabilities.

There are a few roles which do not follow the above convention.

| Role | Access Level | Meaning |
| --- | --- | --- |
| `admin` | highest | Can manage anything (see below) |
| `user_support_manager` | varied | Tech support role (see below) |

### Admin UI Roles

Below are all the roles available in the FusionAuth Admin UI. There is [additional documentation for the usersupportmanager role](#the-user_support_manager-role) and the [mfadeleter role](#the-mfa_deleter-role).

| Name | Id | Description |
| --- | --- | --- |
| `admin` | `631ecd9d-8d40-4c13-8277-80cedb8236e2` | Can manage everything, including creating new users with administrator privileges. |
| `acl_manager` | `631ecd9d-8d40-4c13-8277-80cedb823712` | Can add and edit IP access control lists. Available since `1.30.0` |
| `acl_deleter` | `631ecd9d-8d40-4c13-8277-80cedb823711` | Can delete IP access control lists. Available since `1.30.0` |
| `api_key_manager` | `631ecd9d-8d40-4c13-8277-80cedb8236e3` | Can add, edit and delete API keys. |
| `application_deleter` | `631ecd9d-8d40-4c13-8277-80cedb8236e4` | Can delete applications. |
| `application_manager` | `631ecd9d-8d40-4c13-8277-80cedb8236e5` | Can add and edit applications. Can also add, edit and delete roles and scopes. |
| `audit_log_viewer` | `631ecd9d-8d40-4c13-8277-80cedb8236e6` | Can view audit logs. |
| `cimd_domain_deleter` | `631ecd9d-8d40-4c13-8277-80cedb823718` | Can delete CIMD domains. To reach the CIMD domain list in the Admin UI, a user also needs `cimd_domain_manager`. Available since `1.70.0` |
| `cimd_domain_manager` | `631ecd9d-8d40-4c13-8277-80cedb823717` | Can add and edit CIMD domains and their custom OAuth scopes. Available since `1.70.0` |
| `connector_deleter` | `631ecd9d-8d40-4c13-8277-80cedb823700` | Can delete Connectors. Available since `1.18.0` |
| `connector_manager` | `631ecd9d-8d40-4c13-8277-80cedb823701` | Can add and edit Connectors. Available since `1.18.0` |
| `consent_deleter` | `631ecd9d-8d40-4c13-8277-80cedb8236fc` | Can delete consents. |
| `consent_manager` | `631ecd9d-8d40-4c13-8277-80cedb8236fd` | Can add and edit consents. |
| `email_template_manager` | `631ecd9d-8d40-4c13-8277-80cedb8236e7` | Can add, edit and delete email templates. |
| `entity_manager` | `631ecd9d-8d40-4c13-8277-80cedb823706` | Can add, edit and delete entities. Available since `1.26.0` |
| `event_log_viewer` | `631ecd9d-8d40-4c13-8277-80cedb8236fa` | Can view the event log. |
| `form_deleter` | `631ecd9d-8d40-4c13-8277-80cedb823702` | Can delete forms and form fields. Available since `1.18.0` |
| `form_manager` | `631ecd9d-8d40-4c13-8277-80cedb823703` | Can add and edit forms and form fields. Available since `1.18.0` |
| `group_deleter` | `631ecd9d-8d40-4c13-8277-80cedb8236f6` | Can delete groups. |
| `group_manager` | `631ecd9d-8d40-4c13-8277-80cedb8236f5` | Can add and edit groups. |
| `key_manager` | `631ecd9d-8d40-4c13-8277-80cedb8236fb` | Can add, edit and delete keys. |
| `lambda_manager` | `631ecd9d-8d40-4c13-8277-80cedb8236f9` | Can add, edit and delete lambdas. |
| `message_template_deleter` | `631ecd9d-8d40-4c13-8277-80cedb823709` | Can delete message templates. Available since `1.26.0` |
| `message_template_manager` | `631ecd9d-8d40-4c13-8277-80cedb823710` | Can add and edit message templates. Available since `1.26.0` |
| `messenger_deleter` | `631ecd9d-8d40-4c13-8277-80cedb823707` | Can delete messengers. Available since `1.26.0` |
| `messenger_manager` | `631ecd9d-8d40-4c13-8277-80cedb823708` | Can add and edit messengers. Available since `1.26.0` |
| `mfa_deleter` | `631ecd9d-8d40-4c13-8277-80cedb823715` | Can remove a user's multi-factor methods in the Admin UI with additional safety constraints. See below. Available since `1.68.0` |
| `reactor_manager` | `631ecd9d-8d40-4c13-8277-80cedb8236ff` | Can add and edit reactor and license settings, including detaching a license from an instance. Available since `1.15.0` |
| `report_viewer` | `631ecd9d-8d40-4c13-8277-80cedb8236e8` | Can view reports. |
| `system_manager` | `631ecd9d-8d40-4c13-8277-80cedb8236e9` | Can add and edit system configuration. Can also delete themes, manage identity providers, manage integrations with CleanSpeak and Kafka, view system logs and login records, reindex Elasticsearch and see information about the FusionAuth version. |
| `tenant_deleter` | `631ecd9d-8d40-4c13-8277-80cedb8236f8` | Can delete tenants. |
| `tenant_manager` | `631ecd9d-8d40-4c13-8277-80cedb8236f7` | Can add and edit tenants. |
| `theme_manager` | `631ecd9d-8d40-4c13-8277-80cedb8236fe` | Can add and edit themes. |
| `token_exchange_log_viewer` | `631ecd9d-8d40-4c13-8277-80cedb823716` | Can view the token exchange audit log. Available since `1.70.0` |
| `user_action_deleter` | `631ecd9d-8d40-4c13-8277-80cedb8236f0` | Can delete user actions. |
|  |  |  |
| `user_action_manager` | `631ecd9d-8d40-4c13-8277-80cedb8236f1` | Can add and edit user actions. Can also add, edit and delete user action reasons. |
| `user_deleter` | `631ecd9d-8d40-4c13-8277-80cedb8236f2` | Can delete users. |
| `user_manager` | `631ecd9d-8d40-4c13-8277-80cedb8236f3` | Can add and edit users. Please note that because this role can fully manage users, it is similar to the `admin` role. The `user_support_manager` role is recommended in most cases. |
| `user_support_manager` | `631ecd9d-8d40-4c13-8277-80cedb823704` | Allows for a limited scope of user management. See below. Available since `1.23.0` |
| `user_support_viewer` | `631ecd9d-8d40-4c13-8277-80cedb823705` | Can view user information. Available since `1.23.0` |
| `webhook_event_log_viewer` | `631ecd9d-8d40-4c13-8277-80cedb823713` | Can view the webhook event log. Available since `1.53.0` |
| `webhook_manager` | `631ecd9d-8d40-4c13-8277-80cedb8236f4` | Can add, edit and delete webhooks. |

### The user\_support\_manager Role

The `user_support_manager` role is a role tuned for tier 1 technical support personnel and has a mix of capabilities. A user with such a role can:

| Domain | Ability |
| --- | --- |
| consents | Manage consents. |
| email | Send a verify email request. |
| passwords | Send a forgot password request. |
| passwords | Require a password change at next login. |
| group | Manage group membership. |
| family | Manage family membership. |
| registration | View a registration. |
| registration | Add a registration with no role management. If a new registration is created it would receive the default roles only. Cannot add a role to the FusionAuth Admin UI application. |
| registration | Edit a registration with no role modification. |
| registration | Delete a registration. |
| user | Add a user. |
| user | Edit a user, except for any identity information that could be used to authenticate. For example, the email and username cannot be modified. |
| user | Lock a user account. |
| user | Unlock a user account. |
| user | View 2FA settings if available. |
| user | Action a user. |
| user | Add a comment to a user. |
| user | Verify a user's email address. |
| tokens | Manage sessions (refresh tokens). |

### The mfa\_deleter Role

The `mfa_deleter` role allows an administrator to remove MFA methods from users in the Admin UI without requiring a one-time code from the target user. To reduce abuse risk, this role has additional constraints:

*   The target user cannot be registered to the FusionAuth admin application.
*   The target user must be notifiable through at least one verified primary identity:
    *   verified email + configured `tenant.emailConfiguration.adminTwoFactorMethodRemoveEmailTemplateId`, or
    *   verified phone number + configured `tenant.phoneConfiguration.adminTwoFactorMethodRemoveTemplateId`.
*   Users with this role removing their own MFA methods still use the standard verification code flow.

Caution

Do not combine `mfa_deleter` with roles that can modify tenant configuration (for example, `email_template_manager`, `message_template_manager`, `tenant_manager`). A user who can both remove MFA methods and change tenant notification templates can weaken these safeguards.

## FusionAuth Tenant Manager roles

Below are all the roles available for use in the Tenant Manager application.

| Name | Id | Description |
| --- | --- | --- |
| `admin` | `631ecd9d-8d40-4c13-8277-80cedb823714` | Can manage everything. |

Related

[APIs Create an Application Role API API documentation for the FusionAuth Create an Application Role API. rbacrole-based access control](https://fusionauth.io/docs/apis/applications/create-an-application-role.md)

[APIs Delete an Application Role API API documentation for the FusionAuth Delete an Application Role API. rbacrole-based access control](https://fusionauth.io/docs/apis/applications/delete-an-application-role.md)

[APIs Update an Application Role API API documentation for the FusionAuth Update an Application Role API. rbacrole-based access control](https://fusionauth.io/docs/apis/applications/update-an-application-role.md)

[APIs Create a Group API API documentation for the FusionAuth Create a Group API. role assignment](https://fusionauth.io/docs/apis/groups/create-a-group.md)
---

## Other pages in Types

> For the full index of this section, see [Concepts](https://fusionauth.io/docs/llms-concepts.txt).

- [Applications](https://fusionauth.io/docs/concepts/types/applications.md): Learn about applications, which represent the apps your users log into.
- [CIMD Domains](https://fusionauth.io/docs/concepts/types/cimd-domains.md): Learn about CIMD domains, which let OAuth clients register themselves with a Client ID Metadata Document.
- [Indexed Entity Fields](https://fusionauth.io/docs/concepts/types/entity-fields.md): Learn about the entity fields that are indexed and searchable.
- [Entity Management](https://fusionauth.io/docs/concepts/types/entity-management.md): Learn about entities, which model machines, services, and other things that aren't users.
- [Groups](https://fusionauth.io/docs/concepts/types/groups.md): Learn about groups, which give roles to many users at once.
- [Core Types](https://fusionauth.io/docs/concepts/types.md): Learn about the core types in FusionAuth and how they interact to manage authentication and authorization.
- [Registrations](https://fusionauth.io/docs/concepts/types/registrations.md): Learn about registrations, which connect users to the applications they can log into.
- [Tenants](https://fusionauth.io/docs/concepts/types/tenants.md): Learn about tenants, which isolate users, applications, and configuration in one FusionAuth instance.
- [Users](https://fusionauth.io/docs/concepts/types/users.md): Learn about users, the people who log into your applications.