Skip to content

Create, edit or delete a custom role

Compose a named set of permissions for your tenant, change which permissions it bundles, or remove it when nobody needs it any more.

Who can do it

A tenant administrator, or a platform super administrator working inside your tenant. Creating, editing and deleting are three separate permissions: the console shows Create Custom Role only to a person who may create roles, and disables the edit and delete icons of a custom row for a person who may not edit or delete them.

On a SaaS deployment, a platform operator working inside your tenant under a support-access session cannot create or edit a role: the request is refused.

Before you start

  • A custom role can bundle only permissions you hold yourself. What you can compose is bounded by your own roles.
  • Some permissions are reserved for the platform plane. They may appear in the checklist because you hold them, but a role that includes one is refused.
  • Built-in (System) roles cannot be edited or deleted.

Steps

  1. Open Roles from your tenant's navigation. The Role Catalog lists the system roles and your tenant's custom roles, with the number of Scopes each carries.
  2. To create a role:
    1. Select Create Custom Role.
    2. Enter a Role Name: uppercase letters, digits and underscores, three to sixty-four characters, starting with a letter. It may not start with PLATFORM_, TENANT_, ANKA_, SYSTEM_, INTERNAL_, S2S_ or AUTH_.
    3. Optionally enter a Description (optional). It is not stored.
    4. Tick at least one permission. Only permissions you hold can be ticked.
    5. Select Create.
  3. To edit a custom role, select its edit icon. The checklist opens with the role's current permissions ticked. Change the selection and select Save Changes. The saved set replaces the previous one entirely.
  4. To delete a custom role, select its delete icon and confirm with Delete. The dialog states that the role cannot be deleted while a user still holds it, or while a federation group mapping or admission rule names it.

What you see when it worked

The console confirms Role created, Role updated or Role deleted, and the list changes at once. Every change is recorded in the audit trail.

The effect on the people who hold an edited role depends on the direction of the change:

  • Adding permissions signs nobody out. Holders have the new permissions on their next request, once the role caches are refreshed.
  • Removing any permission ends the sessions of every holder immediately. Before you save, the dialog warns Saving will sign out everyone holding this role.

A deleted role disappears from the list, and its name can be used again.

If it fails

What you see Cause What to do
Must match ^[A-Z][A-Z0-9_]{2,63}$ (uppercase, digits, underscore; 3–64 chars) under the name The name has the wrong shape Correct the name
Reserved prefix: … under the name The name starts with a prefix the platform reserves Choose a name without that prefix
You hold no assignable scopes. Contact a Platform Admin. You hold no permission a role could bundle Ask an administrator who holds the permissions you want to bundle
Role '<name>' already exists in tenant, or Role name '<name>' collides with a system role The name is taken in your tenant or by a built-in role Choose another name
Unknown scope(s), not present in the scope catalog: … A requested permission does not exist Remove it from the request
The request is refused naming a permission you hold That permission belongs to the platform plane and may not be composed into a tenant role Untick it
A scope-subset refusal A requested permission is one you do not hold, or the role already carries one you do not hold (greyed out with (not held)), which you can neither keep nor remove Ask someone who holds that permission to make the change
Role was modified concurrently; refetch and retry (version mismatch) Someone changed the role after you opened it Close the dialog, reopen it and edit the current version. See Concurrent Modification
Cannot delete role '<name>': <n> active user(s) still hold it. Reassign them first. Active members of your tenant still hold the role Reassign those members, then delete again. Deleted members do not count
Cannot delete role '<name>': a federation group mapping or admission rule still names it. Remove them first. A federation declaration would keep conferring the role Delete the group mapping or admission rule first
System role '<name>' is immutable The role is built in Built-in roles cannot be changed

Without the console

Surface How
API POST /api/v3/admin/tenants/{tenantId}/roles (operation createRole)
API PUT /api/v3/admin/tenants/{tenantId}/roles/{roleName}?version=<version> (operation updateRole)
API DELETE /api/v3/admin/tenants/{tenantId}/roles/{roleName} (operation deleteRole)

No ankasecure-km command and no Admin SDK method manage custom roles.