CMMS Permissions and Service Accounts
CMMS integrations use non-human identities for imports, synchronization, handoff, attachment sync, and controlled write-back. These identities should be scoped by tenant, provider, workflow, and action level.
Use this guide before enabling scheduled imports, API handoff, provider write-back, or AI Agent workflows that read or draft maintenance actions.
Permission Flow
Prerequisites
| Requirement | Why it matters |
|---|
| Integration owner | Each credential needs a business and technical owner |
| Provider scope | The credential should be tied to the provider, site, tenant, and workflow it serves |
| Action boundary | Read, draft, handoff, write-back, attachment sync, and closeout actions need separate approval |
| Secret storage | Credentials must be stored in the approved secret-management process |
| Audit path | Imports, writes, retries, and failures must be traceable |
| Rotation plan | The team needs a planned rotation and emergency revoke path |
| Input | Use |
|---|
| Provider endpoint and environment | Identifies production, staging, private cloud, or on-premises boundary |
| Service account name | Links integration activity to a traceable identity |
| Required provider permissions | Defines what the source CMMS or EAM account can read or write |
| FactVerse scopes | Defines the allowed FactVerse product, DFS, ECM, CMMS, or AI Agent access |
| Tenant and site boundary | Prevents one key from crossing unrelated operating scopes |
| Rotation and expiry policy | Supports credential lifecycle management |
| Audit requirements | Defines what must be recorded for review and compliance |
Access Levels
| Access level | Typical use | Controls |
|---|
| Read-only import | Pull work orders, assets, status, and attachment metadata | Least operational risk; recommended first integration mode |
| Attachment sync | Bring service reports, photos, checklists, and closeout files into ECM | File-size, classification, retention, and access policy |
| Draft handoff | Create a reviewed request or draft for a downstream provider | Supervisor review and provider ownership rule |
| Status synchronization | Update selected status or feedback fields | Conflict rule, retry log, and owner approval |
| Provider write-back | Write approved fields into a downstream CMMS | Narrow field list, rollback plan, and test window |
| AI Agent action draft | Let AI Agent prepare a recommendation or draft work order | Review gate, source citation, and action approval |
Service Account Design
- Create separate service identities for each provider or integration boundary.
- Separate read-only imports from write-back credentials.
- Use different credentials for production, staging, and test environments.
- Limit access to the tenant, site, provider, and workflow in scope.
- Store secrets in the approved deployment or customer secret-management system.
- Record owner, purpose, scopes, expiry, and revoke procedure.
- Rotate credentials on schedule and after owner changes.
Scope Review
| Scope decision | Recommended approach |
|---|
| Tenant boundary | One credential should map to one tenant or deployment boundary |
| Provider boundary | Separate credentials for each CMMS or EAM provider when ownership differs |
| Data boundary | Limit access by site, building, asset group, folder, or dataset when available |
| Write boundary | Separate credentials for read, draft, write-back, and closeout actions |
| AI Agent boundary | Agent workflows should use explicit tool and action scopes with review gates |
Expected Output
At handoff, the project should have:
- service account inventory;
- provider permission matrix;
- FactVerse scope matrix;
- secret storage and rotation owner;
- read/write boundary decision;
- test evidence for authentication and authorization;
- audit and sync-log verification.
Validation Checklist
- Each credential authenticates to the intended environment.
- Tool discovery or API access exposes the expected capabilities.
- Read-only tests run before write or action tests.
- Write-back tests create expected provider and FactVerse audit records.
- Credential removal causes the integration to fail closed.
- Rotation and revoke procedures are documented and tested.
Troubleshooting
| Symptom | Check |
|---|
| Authentication fails | Secret value, provider environment, IP allowlist, expiry, and clock drift |
| Access works in staging but fails in production | Environment endpoint, tenant boundary, provider role, and firewall rule |
| Write-back is denied | Provider field permission, FactVerse scope, workflow approval, and source ownership rule |
| AI Agent cannot call a CMMS tool | Tool scope, service identity, endpoint slice, tenant enablement, and review gate |
| Audit record missing | Action path, service account ID, sync log, provider response, and retry handler |