Skip to main content

​
Overview

Aptly uses a hybrid authorization model that combines three layers:
  1. Role-based permissions (RBAC) — a role grants module access and per-action permissions (View, Create, Edit, Approve, Archive, Delete, and module-specific extended permissions).
  2. Scopes — each permission is set to All, Groups, None, or one of the sharing-aware variants used on Matrices and Documents. Scope determines the records the permission applies to.
  3. Stakeholder relationships (Fine-Grained Authorization) — a user’s relationship to a record (Owner, Issuer, Recipient, Role Designee, Responsible, Reviewer, Approver, Assignee, or shared user/group) grants additional, record-specific access on top of role permissions.
A user’s effective access is the combination of all three layers: they need the role permission, the relevant scope, and — for many actions — the right relationship to the record itself.
Users can be assigned one or more roles. When multiple roles apply, effective permissions are the union of all assigned roles.

​
🧭 How permissions are identified

Aptly permissions are organized into namespaces that group related permissions together. Each permission is referenced as namespace.permission_key:
  • tenant — module access toggles (e.g., tenant.access_decisions_module), settings-management permissions (e.g., tenant.manage_account_settings, tenant.manage_users), and tenant-level resource permissions like tenant.create_decisions and tenant.create_root_delegations.
  • decision, delegation, matrix, document, action, report — record-level permissions for each resource type. For example, decision.view, delegation.approve_deny, matrix.share, document.review.
Scope is a separate dimension layered on top of the permission identifier. A role’s decision.view permission can be set to All, Groups, or None — the identifier itself does not encode scope. The combination of permission + scope + relationship determines effective access at evaluation time.

​
🔍 How access is evaluated

Aptly evaluates access through a layered check:
  1. Module access — does the role allow the user into the module at all? Module access is controlled by the tenant.access_<module>_module permission for each of Decisions, Delegations, Matrices, Actions, Documents, Reporting, and Settings.
  2. Permission + scope — does the role grant the requested action (View, Create, Edit, Approve, etc.) and at what scope (All, Groups, None, or a sharing-aware variant)?
  3. Stakeholder relationship — for many actions, the user must also be in a specific capacity on the record (Owner, Issuer, Recipient, Role Designee, Responsible, Reviewer, Approver, or shared user/group).
  4. Tenant-level configuration — some actions also depend on tenant settings (for example, delegation.approve_deny only generates approval actions when Delegation Approval is enabled in account settings).
Example: approving a delegation requires delegation.approve_deny and the user not being the Issuer of the delegation in question. Editing a Decision typically requires decision.edit and either matching effective group membership or being the Decision Owner.

​
👥 Default roles

Default roles ship with every Aptly tenant and cover the most common enterprise access patterns. They cannot be edited, but they can be duplicated to create custom roles tailored to your governance model.

​
Role lifecycle

  • System Admin can only be duplicated — it cannot be edited or deactivated.
  • Other default roles can be duplicated and may be deactivated/reactivated, but cannot be edited or deleted.
  • Custom roles can be edited, duplicated, deactivated/reactivated, or deleted.
  • A role cannot be deactivated or deleted if it is currently assigned to one or more users.

​
🎯 Permission scopes

Most permissions accept a scope that determines which records the permission applies to. Two scope sets exist, depending on the module:

​
Standard scopes (Decisions, Delegations, Actions)

​
Sharing-aware scopes (Matrices, Documents)

Matrices and Documents use a sharing-aware scope set because access can also come from explicit sharing:
When an admin creates a new role from scratch, all permissions default to None (or the most restrictive option) until access is explicitly granted.

​
🧩 Effective group membership

When a permission is set to Groups, Aptly evaluates group alignment using a user’s effective group membership, which combines:
  • Direct group assignments on the user (Organizations, Locations, Departments, and any custom group types), and
  • Inherited group assignments via the user’s Positions (because Positions can be scoped to groups).
A user may have no groups assigned to them directly and still be subject to group-scoped permissions because their Position is scoped to one or more groups.
Example: a user has no Organizations assigned to them directly, but their Position is scoped to “ProxyComm US.” If a Decision is also scoped to “ProxyComm US” and the user’s role has decision.view set to Groups, the user can view that Decision.
Group alignment also respects parent–child group hierarchies: a user assigned to a parent group is treated as aligned with that group’s child groups for permission evaluation purposes.

​
🔗 Stakeholder-based inherited access

In addition to role permissions, Aptly grants record-specific access based on a user’s relationship to a record. These “stakeholder” capacities ensure that participants can complete their own work without needing broad role permissions. Exactly which actions a stakeholder can take varies by capacity. For example, a Document Approver inherits document.approve_reject, a Reviewer inherits document.review, and an Owner inherits broader management rights such as document.edit, document.archive_restore, document.share, and document.view_change_log. Some stakeholder inheritances are fixed; others are configurable per role.

​
⚖️ Delegation permissions worth understanding

A few delegation-related permissions have non-obvious behavior worth calling out:

​
tenant.create_root_delegations

A Root Delegation is the first delegation issued directly from a published Decision. Without tenant.create_root_delegations, a user cannot start a delegation chain from a Decision — even if they have other delegation permissions.

​
delegation.approve_deny

When Delegation Approval is enabled, Aptly generates a Delegation Approval action for each newly issued delegation (and a separate Pending Re-approval action when a substantive change is made to an Issued delegation). The action is assigned to all eligible approvers based on each user’s delegation.approve_deny scope:
  • Scope = All — the user is eligible for delegation approval actions across the tenant.
  • Scope = Groups — the user is eligible only when their effective group membership aligns with the delegation’s group assignments. Parent–child group inheritance applies.
Approver assignment is first-eligible-to-act: every eligible approver is assigned simultaneously, and the first to approve or deny closes the action for everyone.
Issuer & Recipient guardrail: a designated approver cannot approve a delegation where they are also the Issuer or a Recipient. Exception: when Root Authority is used on a Root Delegation, all eligible approvers are assigned, including the user who created the Root Delegation.

​
delegation.manage_roles_conditions

Controls whether a user can manage Conditions and Roles on a delegation (when those features are enabled on the parent Decision). Issuer, Recipient, and Role Designee inheritance can supplement this for participants, depending on role configuration.

​
tenant.limit_override_delegations

When tenant-level global redelegation limits are configured, a recipient of a delegation can normally redelegate only up to that percentage of the source authority. Users with tenant.limit_override_delegations can redelegate beyond that cap — but the resulting redelegation must still remain within the parent Decision’s authority limits.

​
tenant.change_issuer_delegations and <resource>.change_owner

These permissions are intentionally separated from basic View/Edit so admins can tightly control who can re-assign authority ownership on Decisions, Delegations, Matrices, Documents, and Reports.

​
⚙️ Settings permissions

Settings permissions sit in the tenant namespace and follow a two-tier pattern: a top-level toggle for each Settings area, with sub-permissions where finer control is needed.

​
🛠️ Custom roles

Default roles often need refinement for specific governance models. To create a custom role:
  1. Open Settings → Users & Roles → Roles.
  2. Either click + Add New Role to start from scratch, or use the three-dot menu on an existing role to Duplicate it. Duplicating is recommended — it’s faster and ensures a known-good starting point.
  3. Set the role name and description.
  4. Configure permissions per module (Decisions, Delegations, Matrices, Actions, Documents, Reporting, Settings). Each module has its own Module Access toggle plus Basic and Extended permissions.
  5. Save the role.
Example: a “Regional Legal Manager” role might combine delegation.approve_deny (scope: Groups), decision.view (scope: Groups), and document.edit (scope: Groups or User Shared), with the role assigned to a Legal department group and an EMEA Entities group.

​
✅ Governance practice

  • Start by duplicating the default role closest to the need, then narrow from there. It’s faster than building from scratch and reduces the chance of missing a permission.
  • Prefer Groups-scoped permissions for operational roles to limit overexposure. Reserve All for governance and admin roles.
  • Reserve override toggles (tenant.limit_override_delegations, tenant.change_issuer_delegations, <resource>.change_owner) for a small set of admin and governance roles.
  • Audit visibility separately from change rights. Auditors should see everything, including logs and version history, without being able to modify records. Restricted Users should see only what’s directly shared with them or where they are a stakeholder.
  • Validate effective access with a pilot user. Assign the intended mix of role, groups, Position, and stakeholder capacities, then verify the available actions in the UI before rolling out broadly.
For full per-module permission reference detail, see the Aptly Support Portal articles Role Management, Roles – Permission Scopes & Key Permissions, and the Roles – Permissions Glossary.

​
📘 Related Pages

Need help modeling roles, scopes, and stakeholder capacities to match your organizational structure? Contact [email protected] or visit the Aptly Support Portal.