Documentation Index
Fetch the complete documentation index at: https://docs.aptlydone.com/llms.txt
Use this file to discover all available pages before exploring further.
Overview
Aptly uses a hybrid authorization model that combines three layers:
- Role-based permissions (RBAC) — a role grants module access and per-action permissions (View, Create, Edit, Approve, Archive, Delete, and module-specific extended permissions).
- 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.
- 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:
- 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.
- 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)?
- 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).
- 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 | Description |
|---|
| System Admin | This role provides unrestricted view, edit, archive, and delete access across all modules and records, along with comprehensive control over all system features and configurations — including user management, permissions, system-wide settings, and logs. |
| Global Authority Manager | This role ensures consistent governance and decision-making throughout the organization and across entities. It manages system-wide decision authority, including the creation and administration of decisions, top-level (root) delegations, delegation approvals, matrices, actions, and documents. Excludes system configuration; reporting, logs, and version history access span the tenant. |
| Group Authority Manager | This role focuses on localized authority management within defined organizational boundaries. It manages the authority framework for specific organizational groups, including the creation and administration of decisions, top-level (root) delegations, delegation approvals, matrices, actions, and documents. Excludes system configuration. Logs and version history access are scoped to the group; reporting access spans the tenant. |
| Global User | This role is suited for broad operational involvement within the organization. It provides operational-level access to view all decisions, delegations, matrices, actions, and documents. Users with this role can request authority but can only sub-delegate authority granted to them directly. Management rights (archive, share, delete) and version history access are limited to records where they are directly involved as an owner, issuer, or recipient. |
| Group User | This role ensures compartmentalized access for localized operations. It provides operational-level access to view group decisions, delegations, matrices, actions, and documents. Users with this role can request authority but can only sub-delegate authority granted to them directly. Management rights (archive, share, delete) and version history access are limited to records where they are directly involved as an owner, issuer, or recipient. |
| Restricted User | This role is ideal for minimal access needs and secure collaboration. It grants restricted view-only access to specific records that are directly shared with them or where they are designated as an owner, issuer, or recipient. Users with this role have no change log or version history access and cannot create, edit, or manage records. |
| Auditor | This role is suitable for both internal and external auditors, as well as compliance teams requiring read-only access to verify authority records without making modifications. It provides view-only access to all decisions, delegations, matrices, actions, documents, and reports — including change logs and version histories — ensuring complete transparency and traceability for point-in-time authority validation and governance auditing. |
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)
| Scope | Meaning |
|---|
| All | The permission applies to every record in the module. |
| Groups | The permission applies only when the record’s group assignments align with the user’s effective group membership (see below). |
| None | The role grants no access for that permission. |
Sharing-aware scopes (Matrices, Documents)
Matrices and Documents use a sharing-aware scope set because access can also come from explicit sharing:
| Scope | Meaning |
|---|
| Global | The permission applies across all records in the module. |
| Groups or User Shared | The permission applies if the record is group-aligned or explicitly shared to the user. |
| User Shared | The permission applies only when the record is explicitly shared to the user. |
| None | The role grants no access for that permission. |
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.
| Module | Stakeholder relationships that inherit access |
|---|
| Decisions | Owner |
| Delegations | Issuer, Recipient, Role Designee |
| Matrices | Owner, shared users/groups |
| Actions | Owner, Assignee |
| Documents | Owner, Responsible, Reviewer, Approver, shared users/groups |
| Reporting | Owner |
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.
| Permission | Controls |
|---|
tenant.access_settings_module | Whether the Settings module appears in left navigation. |
tenant.manage_account_settings | Access to all Account Settings pages (Info & Region, Group Types, Positions, Decisions, Delegations, Matrices, Documents, Actions). |
tenant.manage_users | Top-level access to the Users tab. Sub-permissions: tenant.view_users, tenant.create_users, tenant.edit_users, tenant.delete_users. |
tenant.manage_roles | Top-level access to the Roles tab. Sub-permissions: tenant.view_roles, tenant.create_roles, tenant.edit_roles, tenant.delete_roles. |
tenant.manage_groups | Access to the Groups area under Settings. |
tenant.manage_notifications | Access to the Notifications area under Settings. |
tenant.view_access_logs | Access to User Access Logs under Advanced. |
tenant.manage_user_api_keys | Access to User Access Keys under Advanced. |
tenant.manage_api_keys | Access to Access Key Management under Advanced. |
tenant.manage_subscription | Access to Subscription and Billing. |
tenant.access_integrations_dashboard | Access to the Integrations Dashboard. |
tenant.access_integrations_marketplace | Access to the Integrations Marketplace. |
tenant.access_integrations_workflows | Access to the custom workflow builder (subscription tier dependent). |
🛠️ Custom roles
Default roles often need refinement for specific governance models. To create a custom role:
- Open Settings → Users & Roles → Roles.
- 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.
- Set the role name and description.
- Configure permissions per module (Decisions, Delegations, Matrices, Actions, Documents, Reporting, Settings). Each module has its own Module Access toggle plus Basic and Extended permissions.
- 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
