Configure roles

Configure via Logto Console

Define role type

In Logto, there are two types of roles based on the entity it can be applied "User role" or "Machine-to-machine app role".

1. User role: User role is a type of role only assignable to users. It can include permissions from your own API resources.
2. Machine-to-machine role: M2M role is a type of role only assignable to machine-to-machine apps. It can include both your own API permissions and Logto Management API permissions. Machine-to-machine role is usually used to protect your machine-to-machine authentication. Such as accessing Logto Management API or your own API resources.

After creating a role, you cannot modify its type.

Create and define a new role

A role is a group of permissions. Navigate to Console > Roles , and you'll see a list of roles you've defined.

1. Keep in mind that while it is technically possible to create a role without permissions or users assigned, it is not recommended to create too many empty roles. This will disrupt the harmony of role management and render the RBAC system ineffective.
2. Permissions are grouped by API in the selector, allowing you to add them in bulk or select them individually.

note

Role-based access control (RBAC) is used across the entire Logto infrastructure, both at the system/user-level and the organization level. This chapter focuses on system/user-level RBAC. If you need to implement RBAC at the organization level, refer to the organization template.

View or update a role

You can also edit the role name and description, and inspect and manage the permissions and users assigned to the role at any time.

warning

Deleting the role will eliminate all the permissions linked to it for the impacted users and delete the connection between roles, users or apps, and permissions.

Manage users or machine-to-machine apps in roles

Depending on the type of role you choose, you will be able to assign or remove users or machine-to-machine applications on the role details page.

Click the "Users" or "Machine-to-machine apps" tab to view the users or apps assigned to the role. To continue adding user(s) or app(s) to the role, click the "Assign users" or "Assign applications" button in the top right corner.

Manage permissions in roles

If you need to change the capabilities of a role, you can easily do so by assigning or removing permissions.

note

If a permission is deleted, users or apps with this role will lose the access granted by this permission.

Manage roles assigned to a machine-to-machine app or user

You can find a "Roles" tab on the details page of a user or an app. Click the tab to view and manage the roles assigned to the user or machine-to-machine apps.

If the configuration in Logto Cloud is not enough for you, you can leverage Management API to perform this management task programmatically.

Configure via Logto Management API

Manage using the Logto Management API. Make a call to the relative end point. Check out this reference.

method	path	description
GET	/api/roles	Get roles with filters and pagination.
POST	/api/roles	Create a new role with the given data.
GET	/api/roles/{Id}	Get role details by ID.
DELETE	/api/roles/{Id}	Delete a role with the given ID.
PATCH	/api/roles/{Id}	Update role details. This method performs a partial update.
GET	/api/roles/{Id}/users	Get users who have the role assigned with pagination.
POST	/api/roles/{Id}/users	Assign a role to a list of users. The role must have the type User.
DELETE	/api/roles/{Id}/users/{userId}	Remove a role from a user with the given ID.
GET	/api/roles/{Id}/applications	Get applications that have the role assigned with pagination.
POST	/api/roles/{Id}/applications	Assign a role to a list of applications. The role must have the type Application.
DELETE	/api/roles/{Id}/applications/{applicationId}	Remove the role from an application with the given ID.
GET	/api/roles/{Id}/scopes	Get API resource scopes (permissions) linked with a role.
POST	/api/roles/{Id}/scopes	Link a list of API resource scopes (permissions) to a role. The original linked scopes will be kept.
DELETE	/api/roles/{Id}/scopes/{scopeId}	Unlink an API resource scope (permission) from a role with the given ID.

Default roles

Default roles are the automatically assigned roles when the users are created, either for the self-sign-up or created through Management API. You can enable this toggle by going to roles-role detail-general.