Tenant Roles
What this screen is for
A role is a named set of API permissions. A person receives the permissions by being assigned the role, and loses them when it is taken away; a role changes nothing until someone holds it. This screen lists the roles your tenant can see and is where you compose your own.
The list has two kinds of row. System roles are built in, marked with a lock, and cannot be edited or deleted here. Custom roles belong to your tenant: you name them, choose the permissions they bundle, edit them and delete them. Each row shows the role's name, its type and how many permissions it carries.
Every built-in role of the installation is listed, including the platform ones (PLATFORM_…). Those are shown, not offered: a platform role cannot be assigned to a user of your tenant.
What must exist first
Both SIMPLE and STANDARD tenants use this screen. Before you work here:
- The permission to read roles, which is what shows the list. The sidebar entry also appears if you hold the permission to create, update or delete roles; without the read permission the screen opens and reports that the roles could not be loaded.
- The permission to create, update or delete custom roles, each held separately. Create Custom Role is shown only with the first; the edit and delete icons of a custom row are disabled without the other two.
- Your own permissions. A custom role can bundle only permissions you hold yourself, so what you can compose is bounded by your own role.
On a SaaS deployment, a platform operator working inside your tenant under a support-access session cannot create or edit a role here: the request is refused.
Decisions you make here
Creating a custom role
Create Custom Role asks for a Role Name, an optional Description and the permissions to bundle. The name is uppercase letters, digits and underscores, three to sixty-four characters, and may not start with PLATFORM_, TENANT_, ANKA_, SYSTEM_, INTERNAL_, S2S_ or AUTH_; the dialog says so as you type, and the platform checks the same rules again. A name your tenant already uses, or that collides with a system role, is refused.
The checklist offers every permission you currently hold, and you must tick at least one. The refusals to expect:
- A permission you do not hold cannot be ticked, and if one reaches the platform anyway it is refused.
- A permission the platform reserves for its own plane is refused even though you hold it. A tenant administrator holds a few of these — the reads of the deployment's policies — and they appear in the checklist; ticking one is refused, because a platform-exclusive permission may not be composed into a role of a regular tenant. The refusal names the permission.
The Description is accepted and discarded: nothing stores it, and the list never shows one.
Using a custom role
A custom role is meant for people. It cannot be held by a cryptographic actor: an actor's roles are capability scopes, never a role composed here.
The Users screen does not offer custom roles either. Its role picker lists only the built-in tenant roles (TENANT_…), so a custom role reaches a person only through the Admin API's user-roles operation. Once assigned that way, the person's Roles tab shows it as a legacy granular assignment, and Save there preserves it.
Editing a custom role
The edit icon of a custom row opens the same checklist with the role's current permissions ticked, plus every permission you hold. Save Changes replaces the role's permission set with exactly what is ticked.
A permission the role carries but you do not hold is greyed out: you cannot add or remove it, and because a saved set may contain only permissions you hold, such a role cannot be saved by you at all until someone who holds that permission removes it. The same is true of a platform-exclusive permission composed before the check existed: the edit is refused until it is dropped.
If someone else changed the role since you opened it, the save is refused; close the dialog and reopen it to edit the current version.
The effect on the people who hold the role is asymmetric, and the dialog warns you before the case that matters:
- Adding permissions signs nobody out. Every holder has the new permissions on their next request, once the caches that expand roles are refreshed — immediately when the invalidation reaches them, and within a minute otherwise.
- Removing any permission ends the sessions of every holder immediately: their next request is rejected, they sign in again, and the new session carries the reduced set.
Deleting a custom role
The delete icon asks you to confirm. The deletion is refused while any active user of your tenant still holds the role; the refusal names how many, and the dialog stays open so you can read it. Reassign those users first. Users who were themselves deleted do not count.
A deleted role disappears from the list and its name becomes available again. System roles cannot be deleted.
How it relates to other screens
Roles are assigned to people on the users screen, which offers the built-in tenant roles and shows what each person holds:
Cryptographic actors hold capability scopes rather than roles composed here; their Roles tab is a different vocabulary: