A role is a named set of permissions. You assign roles to users, and edge turns the roles in a user’s token into an authorization decision. For the conceptual picture, see Entities.
Fields
| Field | What it is | Rules |
|---|---|---|
| Role ID | The name stored on users and in the token’s roles claim | Lowercase letters, digits and hyphens, starting with a letter (^[a-z][a-z0-9-]*$), for example accountant or oauth-admin. No underscores, colons or dots. Unique within the tenant. Cannot be changed after creation |
| Description | A label for the role, shown in the console | Required, in English |
| Active | Whether the role grants access. A switch in the create form and in the General group of the role | On by default. An inactive role stays assigned to its users, but edge grants none of its permissions until it is switched on again. It stays in the list with an Inactive badge. The switch is locked for a role listed under Default roles: take the role off that list first |
| Permissions | The permissions the role grants | Zero or more, from the same tenant |
The list filters roles by All, Active, Inactive and Default for sign-up.
The form and the Central API set no maximum length for the ID or the description.
Note: The hint under the Role ID field in the console reads “Lowercase letters, numbers, underscore, start with letter”. The validation behind it, in both the console and the Central API, accepts hyphens and rejects underscores.
How a role is used
Roles are assigned to users per tenant. The same person can be accountant in one tenant and hold no role in another. The assignment is stored with the user in auth, and the role itself lives in central.
The role IDs a user holds in the token’s tenant go into the token’s roles claim when the token is issued. At request time edge unions the permissions of all those roles to decide which endpoints are reachable. A role that is not active contributes nothing.
Because the roles claim is fixed at issuance, removing a role from a user reaches the user’s next issued or refreshed access token. Changes to what a role grants are different: edge applies them after its next configuration refresh, also for tokens already issued. See When a change takes effect.
Editing and deleting
You can change the description, the active state and the permissions. The role ID appears under the page title and cannot be edited.
Deleting a role removes only the role record, after a confirmation. Users keep the assignment, but the ID no longer maps to any permission, so it grants nothing. Set Active off instead if you want to retire a role and keep its definition. A role listed under Default roles in Security cannot be deleted: the console disables the button and Central answers 409. Take it off that list first.
Next steps
- How to register a role: the form, step by step.
- How to register a user: assign roles to a user.
- Permission: what a role is made of.