permission_levels

Create a Permission Level with its name, rules and dashboard access, in one transaction.

Code
Parameters
----------
name : str
    1-100 characters, unique ignoring case.
rules : list of dict, optional
    ``{rule, access, locked}``. A rule with no path, a leading "/", an invalid pattern or a repeated path is
    refused.
dashboards : list of dict, optional
    ``{dashboard_id, is_home}``; at most one home page.

Returns
-------
dict
    The new level, as ``retrieve_permission_level`` returns it.

Add a new, blank rule row (no path, 'none' access) to a Permission Level.

Code
The path is stored as NULL, which no engine applies, until ``update_permission_level_rule`` sets one.

Parameters
----------
permission_level_id : str
    UUID of the Permission Level to add the rule to.

Returns
-------
dict
    ``{id, permission_level_id, rule, access, locked}``

Delete a Permission Level and all of its rules (cascade).

Code
Refused while any of its rules is locked: unlock them first.

Parameters
----------
id : str
    UUID of the Permission Level.

Returns
-------
dict
    ``{"deleted": true}``

Delete a Permission Level Rule.

Code
Parameters
----------
id : str
    UUID of the rule to delete.

Returns
-------
dict
    ``{"deleted": true}``

Every Permission Level for the page's list, by name: counts, not rules.

Code
Returns
-------
list of dict
    ``{id, name, rule_count, locked_rule_count, problem_rule_count, dashboard_count}``

Every role that can sign in, except Administrator, with its default Permission Level, by name.

Code
Returns
-------
list of dict
    ``{id, name, permission_level_id}``

Get one Permission Level as the Settings > Permissions page edits it.

Code
Parameters
----------
id : str
    UUID of the Permission Level.

Returns
-------
dict
    ``{id, name, rules: [{id, permission_level_id, rule, access, locked, area, pattern_match_count,
    problems, empty_text_path}], dashboards: [{id, dashboard_id, is_home}], engine_version}``. ``area`` is the
    rule's registry group, ``pattern_match_count`` how many registry paths a pattern rule matches, ``problems``
    what makes the rule unusable (``domain.permission_rules``), and ``empty_text_path`` whether a rule with no
    path is stored as empty text, which the V2 engine matches against every path (NULL never matches).
    ``engine_version`` is the site's permission engine, ``v1`` or ``v2``. ``revision`` fingerprints the name,
    rules and dashboards; ``update_permission_level`` needs it back.

List every Permission Level with its full rule set.

Code
Distinct from auth.retrieve_permission_levels (id/name only, no
permission gate, used by external MCP/OAuth consumers to enumerate
levels for a picker). This is the admin-page detail view.

Returns
-------
list of dict
    Each entry has ``id``, ``name`` and ``rules`` (a list of
    ``{id, permission_level_id, rule, access, locked}``), ordered by
    level name.

Assign a Role's default Permission Level, or clear it.

Code
Only roles the classic Permissions page offers are accepted: the role
must be able to log in, and the Administrator role is rejected.

Parameters
----------
role_id : str
    UUID of the Role.
permission_level_id : str or None
    UUID of the Permission Level to assign. An explicit ``null`` clears
    the assignment. The parameter carries no default on purpose -- if it
    were optional, a malformed call sending only ``role_id`` would take
    the clear path and silently drop the role's existing level instead of
    being rejected as incomplete.

Returns
-------
dict
    ``{id, name, permission_level_id}``

Save a whole Permission Level: its name, rules and dashboard access, in one transaction.

Code
The level becomes what is sent. A rule with an ``id`` updates that rule, one without is added, and a stored rule
left out is removed; dashboards follow the same rule by ``dashboard_id``. The save is refused, and nothing is
written, when ``revision`` is not the level's current one ("This level changed since you opened it"), when it
changes the path or access of a rule locked in storage or removes one, or when a rule it adds or changes has a
blocking problem. Each change writes the classic page's Settings note.

Parameters
----------
id : str
    UUID of the Permission Level.
name : str
    1-100 characters, unique ignoring case.
rules : list of dict, optional
    ``{id?, rule, access, locked}``.
dashboards : list of dict, optional
    ``{dashboard_id, is_home}``; at most one home page.
revision : str
    Required. The ``revision`` ``retrieve_permission_level`` returned for the level being edited; a save without
    one is refused.

Returns
-------
dict
    The saved level, as ``retrieve_permission_level`` returns it.

Rename an existing Permission Level.

Code
Parameters
----------
id : str
    UUID of the Permission Level.
name : str
    New name, 1-100 characters, unique ignoring case.

Returns
-------
dict
    ``{id, name, rules: [...]}``

Update a Permission Level Rule.

Code
Any subset of the mutable fields may be provided; omitted or null fields
are left unchanged, and at least one must be given. A new path or access
is refused when the rule is locked (unlock it first, in its own call), and
when the path is empty, starts with a slash, is not a valid pattern, or
repeats another rule in the level.

Parameters
----------
id : str
    UUID of the rule to update.
rule : str, optional
    Permission path the rule grants access to, max 500 characters.
access : str, optional
    One of ``none``, ``r``, ``rw``.
locked : bool, optional
    Whether the rule is locked: a locked rule keeps its path and access and cannot be deleted.

Returns
-------
dict
    ``{id, permission_level_id, rule, access, locked}``

Set several roles' default Permission Levels in one transaction.

Code
Parameters
----------
assignments : list of dict
    ``{role_id, permission_level_id}``; ``null`` clears a role's level. Only the roles
    ``list_role_permission_levels`` lists are accepted.

Returns
-------
list of dict
    Every role, as ``list_role_permission_levels`` returns them.