Maestro and AuthZ: How to resolve permission divergence between Admin and Maestro

As Maestro moves to the centralized AuthZ platform as the single source of truth for who can view, create, edit, and manage workflows, users may see scenarios in which the Admin UI and Maestro are not synchronized regarding a user’s access.

This article explains why those divergences happen, how to recognize them, and the most reliable way to fix them so Maestro and Admin stay in sync.

High-level overview

• AuthZ stores relationships between users/accounts and Maestro resources and is verified by Maestro on each action (create, edit, publish, view).
• Moving enforcement into AuthZ improves consistency and security, but it can reveal differences between what the Admin UI displays and what Maestro enforces.
• These differences typically appear when permissions were applied through multiple channels (Admin web UI, user/group assignments, or the eSignature API).

Why permission divergence happens

Customers can configure permissions in multiple ways: directly on users, via user groups, in Permission Profiles, or using the eSignature API. When you use the API to add Maestro-specific permissions, those changes may not always produce the same AuthZ relationships that Maestro expects. In short:

• The Admin web UI shows a Permission Profile state.
• The eSignature API can set Maestro-specific permissions (none, create, prepare, manage) at profile, user, or group scope.
• API-based or mixed changes can create situations where the Admin UI’s representation and the AuthZ relationships used by Maestro diverge.

Example: setting Maestro permissions via the eSignature API

You can update a Permission Profile to grant Maestro access using the AccountPermissionProfiles resource. Example endpoint and request body:

PUT /restapi/v2.1/accounts/{accountId}/permission_profiles/{permissionProfileId}

{  
​​​​​​​"permissionProfileName": "My Updated Permission Profile",   
"settings": {     
"allowedOrchestrationAccess": "manage"  
}
} 

Even when the Admin UI displays Maestro = "manage" for that profile, Maestro may still not allow the user to create or manage workflows if the underlying AuthZ relationships were not refreshed the way Maestro expects.
 

How to recognize a divergence issue

Treat it as a permission divergence when:

• The Maestro UI does not match expected access (missing or greyed actions such as Create, Edit, Publish).
• Admin > Permission Profiles (or the API) indicates the user should have Maestro access, but the user’s Maestro experience does not reflect it.
• Admin tools and API say the user has permissions, but Maestro enforces fewer capabilities — indicating AuthZ does not yet reflect the same relationships.

Recommended fix: Reset permission profiles in the Admin UI

The most reliable remediation is to update (reset) the affected Permission Profile in the Admin web UI so AuthZ ingestion is retriggered. Applying the change from the Admin interface forces a resync of the permission relationships that Maestro consumes.

Step-by-step: Fixing the divergence

1. Sign in to Docusign Admin.
2. Go to Admin > Permission Profiles.
3. Find the Permission Profile assigned to the affected user(s).
4. Edit the Permission Profile and locate the Maestro permissions section.
5. Select the desired Maestro permission level (none, create, prepare, or manage).
6. Click Save. Saving the profile forces an AuthZ resync/ingestion.
7. Have the affected user sign out and sign back into Maestro (or wait a few minutes for propagation), then confirm the Maestro UI reflects the updated capabilities.

Best practices to avoid future divergence

1. Prefer making profile-level permission changes in the Admin UI when possible — the UI save ensures AuthZ ingestion runs as expected.
2. If you must use the API, follow up with a profile save in Admin for any users/groups that will use Maestro, or build in a verification step that ensures AuthZ relationships were established.

Additional resources

• Account Permission Profiles (eSignature REST API)
• Docusign Support & Documentation — search for Maestro permissions and AuthZ

Join the conversation

Have you seen this exact divergence, or do you use an API-first workflow for permissions? Share your experience or questions in the comments — we’ll help troubleshoot and collect feedback to improve our guidance.