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".
- User role: User role is a type of role only assignable to users. It can include permissions from your own API resources.
- 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.
- 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.
- Permissions are grouped by API in the selector, allowing you to add them in bulk or select them individually.
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.
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.
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.