Skip to main content

Managing Roles

note

Managing roles requires a role with the roles:read/roles:create/ roles:update/roles:delete/roles:assign scopes — see the API Reference for the scope each endpoint requires, and Using o2idctl for how to log in.

A role is a named set of scopes (fine-grained permissions like applications:read or users:update). A user can hold multiple roles at once; their effective permissions are the union of scopes across every role they're assigned.

A user's role scopes are only half of what determines a token's actual permissions, though: the application they log in through also has its own allowed scopes, and a token can never carry more than the intersection of the two.

Creating a role​

./o2idctl roles create --name Support --scope applications:read

Repeat --scope to grant more than one scope. See the API Reference — each endpoint's description names the scope it requires.

Listing and inspecting roles​

./o2idctl roles list
./o2idctl roles get <roleId>

Updating a role​

./o2idctl roles update <roleId> --name "Support Updated" --scope applications:read --scope users:read

--name and --scope are both optional — omit --name to keep the current name, and omit --scope entirely to keep the current scopes. Passing --scope at all replaces the full scope list; it isn't merged with the existing one.

Assigning and unassigning roles​

./o2idctl users assign --user <userId> --role <roleId>
./o2idctl users unassign --user <userId> --role <roleId>

Assigning a role a user already holds, or unassigning one they don't, is a no-op rather than an error.

Deleting a role​

./o2idctl roles delete <roleId>

A role can't be deleted while it's still assigned to any user — unassign it from every user first. This also means an admin can never accidentally delete the role granting their own access.

See the CLI Reference for the full roles command list, and the API Reference for the underlying /roles API.