Permissions and Governance
ECM access is controlled by tenant access, user roles, folder permissions, document classification, policy rules, and audit records. The goal is to let teams use documents in daily work while keeping sensitive content, downloads, public links, and compliance evidence under control.
Ask the tenant administrator or project administrator to grant access before starting a document workspace.
Access model
Common access levels
| Access level | Typical actions |
|---|---|
| Viewer | Browse folders, search documents, open allowed records, and view approved metadata. |
| Consumer | Viewer actions plus preview or download when granted by policy. |
| Contributor | Upload, update metadata, check in new versions, and add tags in assigned areas. |
| Steward | Manage folder quality, review tags, route documents, restore records, and prepare evidence packages. |
| Governance administrator | Manage policies, connector access, audit export, retention, and high-risk access changes. |
Use the narrowest role that supports the user's work. Download, public sharing, audit export, and permanent deletion should be granted carefully.
Folder and document access
Folder access controls who can work inside a folder tree. Document-level access can be used for exceptions where a file needs stricter handling than the folder around it.
Recommended approach:
| Situation | Suggested control |
|---|---|
| Most documents in a team area share the same audience | Use folder access. |
| One document is more sensitive than nearby documents | Add document-level access or a higher classification. |
| A contractor needs temporary review access | Use a specific role, folder scope, and expiration process. |
| A user can manage metadata but should not download source files | Grant edit or steward work without download. |
| A public link is needed for handover | Require explicit share permission, expiration, and audit review. |
Classification
Classification describes the sensitivity of a document. It should be assigned according to the customer's information handling policy.
| Classification | Typical content |
|---|---|
| Public | Published manuals, public product information, released training material. |
| Internal | Routine operating documents, internal SOPs, maintenance records. |
| Confidential | Vendor data, sensitive site layouts, process details, customer-specific reports. |
| Restricted | Highly sensitive engineering, security, regulatory, or contractual material. |
Classification should be reviewed when documents are imported, approved, shared, or moved to a broader audience.
Policy center
Policies help administrators define rules that apply across folders and document types.
Examples:
| Policy area | Example control |
|---|---|
| Download control | Only approved roles can download confidential documents. |
| Share control | Public links require explicit permission, expiration, and audit. |
| Retention | Compliance records must be retained according to the customer policy. |
| Review | Draft SOPs must be approved before use in operations. |
| Connector imports | Imported files must be reviewed before becoming official evidence. |
| AI usage | AI workflows can use only authorized and traceable document versions. |
Policies should be tested with representative users before a production rollout.
Structured rule authoring
Use the structured rule builder for common policy conditions before editing raw JSON. The builder should cover the fields most administrators use first: classification, document type, folder, action, principal ID, and principal role. Review the generated JSON rule before saving when the policy controls downloads, sharing, or AI usage.
High-risk policy acknowledgement
An enabled tenant-wide DENY policy is treated as high risk because it can block broad document access. Creating or updating that policy requires an explicit acknowledgement in the request body:
{
"scopeType": "TENANT",
"effect": "DENY",
"enabled": true,
"highRiskAcknowledged": true
}
The acknowledgement is required for create and update operations. Toggle operations still require policy edit permission, but they should be reviewed operationally before enabling a tenant-wide deny rule.
Audit
Audit records help teams answer who accessed or changed documents and when.
Typical audit questions:
| Question | Evidence to check |
|---|---|
| Who uploaded this document? | Upload event, owner, timestamp. |
| Who changed the metadata or tags? | Update event and before-after details. |
| Which version was used? | Version history and linked workflow record. |
| Who downloaded or shared a document? | Download or share-link event. |
| What was included in a compliance pack? | Pack generation record and source document versions. |
Audit exports may include sensitive information. Limit export permission to administrators or approved compliance owners.
Audit export tasks
Small audit exports can be downloaded directly from the current filtered query. For larger audit evidence packages, create an asynchronous export task. The task stores the query snapshot, current user, status, row count, file size, and download artifact so the user can leave the page and return to the export history.
Audit export task statuses:
| Status | Meaning |
|---|---|
PENDING | The export task has been created and is waiting to run. |
RUNNING | Events are being queried and written to the CSV artifact. |
SUCCEEDED | The export artifact is ready to download. |
FAILED | The export failed and includes a failure reason. |
CANCELED | The requester canceled the export before completion. |
Only users with ecm.audit.export can create, list, cancel, and download audit export tasks.
API reference
Use these API contracts when integrating ECM governance tools or verifying migration parity:
| Capability | Endpoint | Permission | Notes |
|---|---|---|---|
| Restore preflight | POST /api/v1/ecm/recycle/preflight-restore | ecm.document.delete | Returns per-item status, conflict target, conflict type, supported strategies, and required permission. |
| Recycle task lifecycle | POST /api/v1/ecm/recycle/tasks, GET /api/v1/ecm/recycle/tasks/{taskId}, POST /api/v1/ecm/recycle/tasks/{taskId}/cancel | ecm.document.delete | Runs large restore, purge, or clear operations with progress and cancellation. |
| Preview support matrix | GET /api/v1/ecm/preview/support-matrix | ecm.document.read | Lists browser-renderable file types and download-only modes. |
| Document preview | GET /api/v1/ecm/documents/{id}/preview | ecm.document.read | Returns inline preview content when the support matrix allows the format. |
| Version preview | GET /api/v1/ecm/documents/{id}/versions/{versionId}/preview | ecm.document.read | Uses the selected version and the same preview support rules. |
| Policy create/update | POST /api/v1/ecm/policies, PUT /api/v1/ecm/policies/{id} | ecm.policy.edit | Tenant-wide enabled deny policies require highRiskAcknowledged: true. |
| Audit export task | POST /api/v1/ecm/audit/exports | ecm.audit.export | Creates an asynchronous CSV export from the supplied query snapshot. |
| Audit export history | GET /api/v1/ecm/audit/exports, GET /api/v1/ecm/audit/exports/{taskId} | ecm.audit.export | Lists the current user's export tasks and task status. |
| Audit export cancel/download | POST /api/v1/ecm/audit/exports/{taskId}/cancel, GET /api/v1/ecm/audit/exports/{taskId}/download | ecm.audit.export | Allows cancellation before completion and artifact download after completion. |
Share links
Share links can expose a document outside the normal application path. Use them only when the project has a clear handover or review purpose.
Before creating a share link, confirm:
- the document owner approves sharing;
- the recipient and purpose are known;
- the link has an expiration date;
- the document version is the intended one;
- the link activity will be audited;
- the link can be revoked when the review is complete.
Governance validation checklist
- Users can see only the folders needed for their role.
- Download access is granted only where it is required.
- Public sharing is limited and audited.
- Sensitive documents have the correct classification.
- Folder access has been tested with at least one viewer and one contributor.
- Policy rules have been tested with representative documents.
- Audit exports are limited to approved users.
- AI Agent workflows inherit the same document access expectations as human users.
Access troubleshooting
| Symptom | Check |
|---|---|
| ECM is hidden | Tenant module access and navigation permission. |
| Folder is visible but document is missing | Folder access, document-level access, classification, and deleted or archived state. |
| Preview works but download is blocked | Download permission or policy rule. |
| Upload is blocked | Contributor or write access for the target folder. |
| Restore or permanent delete is blocked | Recycle or delete permission. |
| Share link creation is blocked | Share permission, document access, and policy rules. |
| Audit export is blocked | Audit export permission. |
| AI Agent cannot use a document | User access, document classification, source version, and indexing status. |