How do I create a custom role?
Short answer
Section titled “Short answer”If the four base roles aren’t enough, create a custom role under Administration → Roles: give it a name, choose permissions from the catalog, and set the scope (this tenant or global). You then assign the role to users — its permissions add to their base role.
Requirements
Section titled “Requirements”Available in all plans.
Instructions
Section titled “Instructions”-
Open Roles. Administration → Roles → “Create role”.
-
Define the role. Enter a name and, optionally, a description, choose the scope (Tenant or Global), and check the desired permissions. Permissions are grouped by area (Assets, Network, …, Administration).
Screenshot pendingadmin-benutzer-07'Create role' form with name, scope and permission selection grouped by areaA custom role bundles any permissions from the catalog. -
Save and assign. After saving, the role appears in the list. Assign it to the relevant accounts via the user detail page (“Assign roles”).
A custom role is created via POST /api/v1/roles. permissions must contain codes
from the permission catalog;
scope is tenant (default) or global.
curl -X POST https://demo.notory.io/api/v1/roles \ -H "Authorization: Bearer inv_dein_token" \ -H "Content-Type: application/json" \ -d '{ "name": "Lizenz-Beauftragte", "description": "Darf Software und Lizenzen pflegen und Berichte lesen.", "permissions": ["software.read", "software.write", "reports.read"], "scope": "tenant" }'Response: 201 Created with the role’s id. You use this ID when assigning it
(PUT /api/v1/roles/assignments/{user_id}).
Possible errors: 403 (not an administrator, or scope: "global" without super
admin rights), 422 (unknown permission code — the message names the invalid code).
What happens behind the scenes?
Section titled “What happens behind the scenes?”- Catalog check. Every permission code you provide is checked against the fixed
catalog; unknown codes are rejected with
422. Notory removes duplicate entries; the order stays stable. - Scope determines visibility.
scope: "tenant"binds the role to your tenant (tenant_idset).scope: "global"(tenant_id = NULL) makes it available to all tenants — hence the super-admin restriction. - Additive, never subtractive. An assigned role extends a user’s permissions. To revoke permissions, remove the role again or lower the base role.
- Custom roles can be deleted. Unlike built-in system roles (
is_system), self-created roles can be edited and deleted at any time. When deleted, assigned users only lose the additional permissions from that role.