Authorisation policy

Included from Basic tier

An authorisation policy bundles path-based access rules with the identities they grant: each rule names a node or platform rule path and the actions it permits (read/update/delete/execute), and each assignment grants the bundle to a user, a group, or everyone. The shipped system policies refuse modification. Served by the v2 AuthorisationPolicyService: the policy CRUD verbs, ReplacePolicyAssignments, the standalone rule CRUD verbs, AttachPolicyRule/DetachPolicyRule, ListPolicyRules and ListRulePathCatalog.

AuthorisationPolicy

AuthorisationPolicy is the full policy view: the row plus its rules and assignments (the v1 include=authorisation_rules,policy_assignments read).

Field	Type	Meaning
assignments	array of PolicyAssignment	The identities the policy grants: user, group and everyone assignments.
created_at	timestamp	When the record was created.
created_by	string	Username of the creating identity.
description	string	Free-text description.
id	string	The record's identity.
name	string	Display name.
rules	array of AuthorisationRule	The policy's linked rules.
system	boolean	True for the shipped system policies, which refuse modification.
updated_at	timestamp	When the record was last updated.
writable	boolean	Whether the caller may write this policy (update, delete, assignments, rule links): a superuser or global security administrator for any policy, a project security administrator for policies whose rule paths all sit under that project; a system policy is writable by a superuser only. The flag the GUI gates its per-policy controls on.

AuthorisationPolicySummary

AuthorisationPolicySummary is one listed policy row.

Field	Type	Meaning
assignments	array of PolicyAssignment	The policy's assignments, populated under AUTHORISATION_POLICY_VIEW_WITH_ASSIGNMENTS.
created_at	timestamp	When the record was created.
created_by	string	Username of the creating identity.
description	string	Free-text description.
id	string	The record's identity.
name	string	Display name.
system	boolean	True for the shipped system policies, which refuse modification.
updated_at	timestamp	When the record was last updated.
writable	boolean	Whether the caller may write this policy — see AuthorisationPolicy.writable.

AuthorisationPolicyView

AuthorisationPolicyView selects how much of each listed policy resolves.

Values: AUTHORISATION_POLICY_VIEW_UNSPECIFIED, AUTHORISATION_POLICY_VIEW_SUMMARY, AUTHORISATION_POLICY_VIEW_WITH_ASSIGNMENTS.

AuthorisationRule

AuthorisationRule is one authorisation rule row linked to the policy.

Field	Type	Meaning
created_at	timestamp	When the record was created.
created_by	string	Username of the creating identity.
deletable	boolean	The rule grants delete on matched paths.
executable	boolean	The rule grants execute on matched paths.
id	string	The record's identity.
name	string	Display name.
path	string	The rule's stored path (strict ^-anchored form).
policy_ids	array of string	The policies this rule is linked to — populated on the standalone rule reads (ListAuthorisationRules/GetAuthorisationRule); empty in a policy's own nested rule view, where the linkage is the enclosing policy.
readable	boolean	The rule grants read on matched paths.
require_step_up	boolean	require_step_up demands an elevated session on the rule's matched write-shaped actions (update/delete/execute) — the composition: the step-up verb floor, then matched rules' bits, then per-object flags; policy only ever ADDS requirements. Enforced under the packs:security-governance entitlement; preserved but inert when the pack lapses.
step_up_on_read	boolean	step_up_on_read opts the rule's reads into the demand too — blanket read step-up is a deliberate, per-rule choice.
updatable	boolean	The rule grants update on matched paths.
updated_at	timestamp	When the record was last updated.
writable	boolean	Whether the caller may write this rule (update, delete): a superuser or global security administrator for any rule, a project security administrator for rules whose path sits under that project. A rule linked to a system policy still refuses modification by name.

AuthorisationRuleInput

AuthorisationRuleInput is one rule in a policy write's rule set (the v1 nested authorisation_rules entry): the rule is found-or-created by its (path, actions) identity and linked to the policy.

Field	Type	Meaning
deletable	boolean	The rule grants delete on matched paths.
executable	boolean	The rule grants execute on matched paths.
path	string	The rule's path, stored in the strict ^-anchored form.
readable	boolean	The rule grants read on matched paths.
updatable	boolean	The rule grants update on matched paths.

AuthorisationRuleSet

AuthorisationRuleSet wraps a policy write's full replacement rule set, so an update distinguishes "replace with this set" (present — an empty set clears every rule) from "leave the rules alone" (absent).

Field	Type	Meaning
rules	array of AuthorisationRuleInput	The full replacement rule set; an empty set clears every rule.

PolicyAssignment

PolicyAssignment is one policy assignment row: a user, an LDAP group (groupname), or everyone (user and group empty). A user assignment is per-identity: user_id names the exact users row it grants, with username/auth_provider carried for display — a same-named account of another provider holds no part of the grant.

Field	Type	Meaning
auth_provider	string	The assigned user's identity provider, carried for display on a user assignment.
created_at	timestamp	When the record was created.
created_by	string	Username of the creating identity.
groupname	string	The group name on a group assignment; empty otherwise.
id	string	The record's identity.
updated_at	timestamp	When the record was last updated.
user_id	string	The exact users row a user assignment grants; empty on group and everyone assignments.
username	string	The assigned user's username, carried for display.

PolicyAssignmentInput

PolicyAssignmentInput is one assignment in the replacement set: a user (user_id, or username while exactly one account holds it — an ambiguous username is refused, since assignments are per-identity), a groupname, or everyone (all empty).

Field	Type	Meaning
groupname	string	A group assignment's group name.
user_id	string	The exact user to assign.
username	string	The user to assign by username — refused when more than one account holds it.

PolicyRule

PolicyRule is one policy_rules join row linking a rule to a policy.

Field	Type	Meaning
authorisation_policy_id	string	The linked policy.
authorisation_rule_id	string	The linked rule.
created_at	timestamp	When the record was created.
created_by	string	Username of the creating identity.
id	string	The record's identity.
updated_at	timestamp	When the record was last updated.

RulePathCatalogEntry

RulePathCatalogEntry is one platform (non-node) rule-path family.

Field	Type	Meaning
description	string	One line a policy author reads: what a rule on this path actually does.
enforcement	RulePathEnforcement	Whether rules on this family are enforced on the decision path or advisory.
node_scope_suffix	boolean	True when the family root takes an appended node-path scope suffix (e.g. /governance/change/projects/web scopes to that subtree).
owning_area	string	The owning area the family belongs to (e.g. Administration, Governance).
path	string	The literal rule path, or a parameterised pattern with placeholders the author replaces (e.g. /admin/groups/, /workflows).

RulePathEnforcement

RulePathEnforcement is the honest enforcement class of a catalog entry.

Values: RULE_PATH_ENFORCEMENT_UNSPECIFIED, RULE_PATH_ENFORCEMENT_ENFORCED, RULE_PATH_ENFORCEMENT_ADVISORY.

Who may change a policy or rule

The gate is the security_administrator role. A management write first needs a superuser or a security_administrator grant — global, or delegated to a project (opschain security roles grant security_administrator <user> --project <code>). Without one every write answers not found, and the refusal is audited as warn:authorisation_policies:refused (the principal id, the target and the reason). Rules whose path ends in /authorisation_policies — upstream's securing prefixes — grant nothing: the upgrade converts their holders into grants under review (opschain docs cli/admin-security-convert-policy-admins). On top of the gate, a project delegate works only inside its project:

• Write scope. A superuser or a global security administrator writes any policy or rule. A project security administrator may update or delete a policy, replace its assignments, and attach or detach its rules only when every rule on the policy sits under the delegated project — the rule path's guaranteed node prefix is the project or a descendant of it; a rule update or delete needs the same of the rule's own path. A policy mixing paths inside and outside the project is outside the delegation. Anything outside that scope answers not found, exactly as an unreadable policy does on a read. A detach must name a link that belongs to the policy in the URL. The served writable flag reports this verdict per policy and per rule.
• Read scope. Reads follow the role too: a superuser, a global security administrator or a global auditor reads every policy and rule; a project security administrator or project auditor reads the policies whose rule paths all sit under the project (and the rules under it); anyone else lists none and gets not found.
• Rule paths. Creating a rule, changing a rule's path, creating or updating a policy with nested rules, and attaching rules all check each path. The path's guaranteed node prefix (its literal head, up to the last complete segment) must be readable to the caller through their rules; an auditor's read-everything grant does not count. A non-superuser may not author a top-level alternation (/a|/b) or a pattern with a wildcard segment followed by literal ones (/projects/foo/.*/deep), because either could match or outrank rules outside what they can see. A refusal answers 422 You do not have permission to manage rules for path: <path>.
• System policies. A system policy (Superuser, Block) refuses modification, including attaching and detaching its rules (422). Its assignments may be replaced by a superuser only, behind the step-up floor — a global security administrator who is not a superuser answers not found — and the Superuser and Block policies cannot be assigned to everyone.

A superuser is unrestricted by the scope and path checks.

Related pages

• opschain docs governance-matrix — the rule-path families and what each one gates.
• opschain docs governance — step-up composition and how the packs:security-governance entitlement enforces it.
• opschain docs resources/group — the groups assignments may name.
• opschain docs resources/user — the per-identity accounts user assignments grant.