Overview

Roles in FusionAuth are associated with an application. 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 upon successful authorization and are also returned as part of the user’s registrations.

You can associate roles with users directly via their registration. Or you can assign an application role to a group, 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

Role Attributes

Roles in FusionAuth have the following attributes:

Namerequired

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

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

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

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

FusionAuth Admin UI Roles

FusionAuth provides an administrative user interface 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 administrative user interface.

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 the administrative user interface screen where you assign roles in the FusionAuth application to a user.

FusionAuth application roles

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:

SuffixAccess LevelMeaning
_viewerlowCan view entities of a particular type
_managerhighCan add or edit the entities
_deleterhighCan 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.

RoleAccess LevelMeaning
adminhighestCan manage anything (see below)
user_support_managervariedTech support role (see below)

Admin UI Roles

Below are all the roles available in the FusionAuth Admin UI. There is additional documentation for the user_support_manager role.

NameIdDescription
admin631ecd9d-8d40-4c13-8277-80cedb8236e2Can manage everything, including creating new users with administrator privileges.
acl_manager631ecd9d-8d40-4c13-8277-80cedb823712Can add and edit IP access control lists. Available since 1.30.0
acl_deleter631ecd9d-8d40-4c13-8277-80cedb823711Can delete IP access control lists. Available since 1.30.0
api_key_manager631ecd9d-8d40-4c13-8277-80cedb8236e3Can add, edit and delete API keys.
application_deleter631ecd9d-8d40-4c13-8277-80cedb8236e4Can delete applications.
application_manager631ecd9d-8d40-4c13-8277-80cedb8236e5Can add and edit applications. Can also add, edit and delete roles and scopes.
audit_log_viewer631ecd9d-8d40-4c13-8277-80cedb8236e6Can view audit logs.
connector_deleter631ecd9d-8d40-4c13-8277-80cedb823700Can delete Connectors. Available since 1.18.0
connector_manager631ecd9d-8d40-4c13-8277-80cedb823701Can add and edit Connectors. Available since 1.18.0
consent_deleter631ecd9d-8d40-4c13-8277-80cedb8236fcCan delete consents.
consent_manager631ecd9d-8d40-4c13-8277-80cedb8236fdCan add and edit consents.
email_template_manager631ecd9d-8d40-4c13-8277-80cedb8236e7Can add, edit and delete email templates.
entity_manager631ecd9d-8d40-4c13-8277-80cedb823706Can add, edit and delete entities. Available since 1.26.0
event_log_viewer631ecd9d-8d40-4c13-8277-80cedb8236faCan view the event log.
form_deleter631ecd9d-8d40-4c13-8277-80cedb823702Can delete forms and form fields. Available since 1.18.0
form_manager631ecd9d-8d40-4c13-8277-80cedb823703Can add and edit forms and form fields. Available since 1.18.0
group_deleter631ecd9d-8d40-4c13-8277-80cedb8236f6Can delete groups.
group_manager631ecd9d-8d40-4c13-8277-80cedb8236f5Can add and edit groups.
key_manager631ecd9d-8d40-4c13-8277-80cedb8236fbCan add, edit and delete keys.
lambda_manager631ecd9d-8d40-4c13-8277-80cedb8236f9Can add, edit and delete lambdas.
message_template_deleter631ecd9d-8d40-4c13-8277-80cedb823709Can delete message templates. Available since 1.26.0
message_template_manager631ecd9d-8d40-4c13-8277-80cedb823710Can add and edit message templates. Available since 1.26.0
messenger_deleter631ecd9d-8d40-4c13-8277-80cedb823707Can delete messengers. Available since 1.26.0
messenger_manager631ecd9d-8d40-4c13-8277-80cedb823708Can add and edit messengers. Available since 1.26.0
reactor_manager631ecd9d-8d40-4c13-8277-80cedb8236ffCan add and edit reactor and license settings, including detaching a license from an instance. Available since 1.15.0
report_viewer631ecd9d-8d40-4c13-8277-80cedb8236e8Can view reports.
system_manager631ecd9d-8d40-4c13-8277-80cedb8236e9Can add and edit system configuration. Can also delete themes.
tenant_deleter631ecd9d-8d40-4c13-8277-80cedb8236f8Can delete tenants.
tenant_manager631ecd9d-8d40-4c13-8277-80cedb8236f7Can add and edit tenants.
theme_manager631ecd9d-8d40-4c13-8277-80cedb8236feCan add and edit themes.
user_action_deleter631ecd9d-8d40-4c13-8277-80cedb8236f0Can delete user actions.
user_action_manager631ecd9d-8d40-4c13-8277-80cedb8236f1Can add and edit user actions. Can also add, edit and delete user action reasons.
user_deleter631ecd9d-8d40-4c13-8277-80cedb8236f2Can delete users.
user_manager631ecd9d-8d40-4c13-8277-80cedb8236f3Can 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_manager631ecd9d-8d40-4c13-8277-80cedb823704Allows for a limited scope of user management. See below. Available since 1.23.0
user_support_viewer631ecd9d-8d40-4c13-8277-80cedb823705Can view user information. Available since 1.23.0
webhook_event_log_viewer631ecd9d-8d40-4c13-8277-80cedb823713Can view the webhook event log. Available since 1.53.0
webhook_manager631ecd9d-8d40-4c13-8277-80cedb8236f4Can 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:

DomainAbility
consentsManage consents.
emailSend a verify email request.
passwordsSend a forgot password request.
passwordsRequire a password change at next login.
groupManage group membership.
familyManage family membership.
registrationView a registration.
registrationAdd 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.
registrationEdit a registration with no role modification.
registrationDelete a registration.
userAdd a user.
userEdit a user, except for any identity information that could be used to authenticate. For example, the email and username cannot be modified.
userLock a user account.
userUnlock a user account.
userView 2FA settings if available.
userAction a user.
userAdd a comment to a user.
userVerify a user’s email address.
tokensManage sessions (refresh tokens).