ADR-0031: Identity Model and Role-Based Access Control
Date: 2026-06-25 Followed by: ADR-0032 (Resource Ownership and Sharing), ADR-0033 (Operational Governance)
Context
Almathal is an enterprise platform deployed into organizations with multiple engineers, multiple teams, and multiple stakeholders with different needs. An IT administrator who manages users and SSO needs different access than a senior architect tracking platform adoption across the organization. A compliance officer reviewing governance outputs needs different access than a developer generating applications.
Without an explicit identity model and RBAC, the platform defaults to one of two bad states: everyone sees everything (violating least-privilege and failing enterprise security reviews), or only one person can do anything (unusable in a real organization).
Almathal operates as a multi-tenant SaaS. Two administrative levels exist and must remain separate:
- The Almathal platform level — operated by Almathal’s own team, touching all customer organizations
- The customer organization level — operated by the customer’s own people, scoped to their organization only
Conflating these would mean a customer administrator could access another customer’s data — a fundamental multi-tenancy violation.
Within the customer organization level, a second conflation must also be avoided: the IT administrator role and the senior technical oversight role are different people with different needs. The infra team person who manages users and executes spending limits does not need to see generated Specs or code. The senior architect who reports to the C-suite on platform adoption does not need to manage SSO or configure teams.
Decision
Organizational Hierarchy
Almathal uses a two-tier hierarchy within each customer organization:
Almathal Platform (multi-tenant) └── Organization └── Team(s) └── User(s)- One Almathal platform instance serves multiple customer Organizations
- An Organization can have multiple Teams
- A User belongs to one or more Teams within their Organization
- Department groupings can be modelled as Team labels where needed
Roles
Six roles are defined. The first is platform-level; the remaining five are organization-level.
Platform Admin
Principal: Almathal’s own employees (not customer staff) Scope: All organizations across the Almathal platform
Operates the Almathal service itself. There are very few of these — only Almathal team members hold this role. Customers cannot assign this role to their own users.
Access to customer data is governed by the break-glass model (see Platform Admin Access section below).
Can:
- Configure the global Archetype and Adapter catalog
- Manage customer Organization accounts (create, modify, deactivate)
- Access any organization’s data through the break-glass process for support and incident response
- View platform-wide spending and usage (all organizations)
- Receive notifications when an organization’s spending limit threshold is reached
Org Admin
Principal: The customer’s IT or infrastructure team member Scope: Administrative operations for their Organization only
The Org Admin is the platform’s operational administrator. Their job is managing the platform, not managing what gets built on it. They do not see generated content — no Specs, no generated code, no generation summaries. They see administrative and operational data.
Can:
- Create, rename, and deactivate Teams
- Invite and remove Users from the Organization
- Assign and revoke roles for any User in the Organization (except Platform Admin)
- Configure SSO integration (SAML/OIDC)
- Set organization-level and team-level and user-level spending limits — the Org Admin is the executor of spending limit decisions; the recommended organizational governance is that the Org Technical Lead authorizes the limit amount before the Org Admin sets it in the system
- View spending and usage observability for the whole Organization (spend by team and user, activity volume)
- View security event logs for their Organization
- Receive and act on spending limit threshold notifications
- Onboard and offboard users
Cannot:
- View Specs, generated code, or generation summaries (who built what, what is the status)
- View audit trails for individual generations
- View governance outputs (SBOMs, provenance records)
- Trigger generations
Org Technical Lead
Principal: A senior architect, principal engineer, or technical director who reports to C-suite on platform adoption Scope: Content visibility and strategic oversight across the whole Organization
The Org Technical Lead is the person who answers “how is our Almathal adoption going?” to the CTO, CFO, and CEO. They need to see what is being built, by whom, in what state, and at what quality. They do not manage the platform’s configuration — that is the Org Admin’s job.
Can:
- View generation summaries across the Organization: how many apps generated, by which team and user, current pipeline status
- View Specs for all generations in the Organization
- View generated code for all generations in the Organization
- View audit trails for all generations in the Organization
- View governance outputs (SBOMs, provenance records, NIST AI RMF mapping) for all generations
- View the adoption metrics dashboard (generation velocity, Archetype usage distribution, quality trends)
- Authorize spending limit changes (organizational governance process — Org Admin executes in the system)
- View spending observability (read-only — cannot set limits)
Cannot:
- Manage Teams, Users, or roles
- Configure SSO or platform settings
- Set spending limits directly in the system (authorizes; Org Admin executes)
- Trigger generations
Team Lead
Principal: An engineering manager or technical lead for one team Scope: Content and administrative access for their Team
Can:
- Invite Users to their Team and remove them
- Set team-level and user-level spending limits (within the Organization’s allocation)
- View generation summaries for their Team (how many apps, by whom, status)
- View Specs for all generations within their Team
- View generated code for all generations within their Team (for code review and PR purposes)
- View audit trails for their Team’s generations
- Share a team member’s generated artifact with the rest of the Team (explicit action — see ADR-0032)
- View team-level spending observability
Cannot:
- Manage other Teams
- View other Teams’ generation details, Specs, or audit trails
- Change organization-level configuration
Developer
Principal: An engineer who uses Almathal to generate applications Scope: Their own generations within their Team
Can:
- Generate applications using available Archetypes
- View, save, and manage their own Specs and generated artifacts
- Access saved Spec templates available to their Team
- View governance outputs for their own generations
- View other team members’ generated code when the Team Lead has explicitly shared it (see ADR-0032)
Cannot:
- View another Developer’s Spec — Specs contain business-sensitive variation point values (entity names, data models, configuration choices). Only the generating Developer, the Team Lead, and the Org Technical Lead see Specs.
- View other team members’ generations unless explicitly shared
- Manage Team membership or spending limits
- Access organization-wide audit trails or governance outputs
Auditor
Principal: A security, compliance, or procurement team member Scope: Governance outputs, audit trails, and generated code (read-only) across the Organization
The Auditor role exists for compliance and procurement. This person does not generate applications. They review governance artifacts and generated code to support the organization’s regulatory obligations — SBOMs, provenance records, NIST AI RMF mappings, and source code verification.
Available from day one. Enterprise procurement conversations happen before and during deployment; compliance teams need this access from the moment Almathal is in use.
Can:
- View governance outputs for all generations in the Organization (SBOMs, provenance records, license reports, NIST AI RMF mapping, vulnerability snapshots)
- View the full audit trail for all generations in the Organization
- View generated source code for all generations (read-only — to verify code matches SBOM and provenance records)
- View security event logs for the Organization
- Export governance packages for regulatory submission
- Access the governance view of the observability dashboard
Cannot:
- View Specs or variation point values
- Trigger generations
- Manage Users, Teams, or roles
- Modify any artifact
Role Summary Table
| Capability | Platform Admin | Org Admin | Org Technical Lead | Team Lead | Developer | Auditor |
|---|---|---|---|---|---|---|
| Configure global Archetype/Adapter catalog | ✓ | — | — | — | — | — |
| Manage Organizations | ✓ | — | — | — | — | — |
| Manage Teams | ✓ | ✓ | — | Own team | — | — |
| Invite/remove Users | ✓ | ✓ (org) | — | ✓ (team) | — | — |
| Assign roles | ✓ | ✓ | — | — | — | — |
| Configure SSO | ✓ | ✓ | — | — | — | — |
| Set spending limits (org level) | ✓ | ✓ (executes) | Authorizes (process) | — | — | — |
| Set spending limits (team/user level) | ✓ | ✓ | — | ✓ | — | — |
| Generate applications | — | — | — | — | ✓ | — |
| View generation summaries (who, how many, status) | ✓ (break-glass) | — | ✓ (org) | ✓ (team) | Own only | — |
| View Specs | ✓ (break-glass) | — | ✓ (org) | ✓ (team) | Own only | — |
| View generated code | ✓ (break-glass) | — | ✓ (org) | ✓ (team) | Own + shared | ✓ (read-only) |
| View governance outputs | ✓ (break-glass) | — | ✓ (org) | — | Own only | ✓ |
| View audit trails | ✓ (break-glass) | — | ✓ (org) | Team only | Own only | ✓ |
| View security event logs | ✓ | ✓ | — | — | — | ✓ |
| View spending observability | ✓ | ✓ (org) | ✓ (read-only) | ✓ (team) | — | — |
| View adoption metrics | ✓ (break-glass) | — | ✓ (org) | Team | — | — |
Platform Admin Access to Customer Data — Break-Glass Model
Platform Admin access to a specific customer organization’s data is restricted by default. Customer data is confidential and is not freely browsable by Almathal’s own team.
Two escalation levels:
Level 1 — Standard support: The Org Admin shares relevant logs, outputs, or screenshots through the normal support channel. Platform Admin advises based on shared information. No special access needed. Appropriate for most support cases.
Level 2 — Break-glass: When diagnosis requires direct platform access to customer data, the Platform Admin initiates a break-glass request with a stated reason and a time-bounded access window.
Break-glass audit trail (API-level logging, not screen recording):
- Session opened: who, which organization, stated reason, approval, window duration
- Every resource accessed during the session: action, resource ID, timestamp
- Session closed: actual duration, resources accessed count
The customer’s Org Admin can see every break-glass access event in their security event log — who accessed, when, and for what stated reason. No surprise access.
This model is disclosed in the Data Processing Agreement.
Data Classification
The distinction between what the Org Admin sees and what the Org Technical Lead sees is grounded in a clear data classification boundary.
Boundary principle: Is this data about the platform itself (who uses it, how much it costs, is it secure, is it operating correctly)? That is administrative/operational data — Org Admin scope. Is this data about what the platform produces (what code, what apps, what AI decisions were made)? That is content/technical data — Org Technical Lead scope.
Administrative and Operational Data (Org Admin)
- User accounts, role assignments, and team memberships
- Team structure and configuration
- SSO configuration and identity provider settings
- Security event logs (break-glass accesses, failed authentications, role change history)
- Spending and usage metrics — amounts spent by team and user, generation counts, API usage volumes
- Platform health indicators — generation success/failure rates, pipeline stage timing, error rates
- Subscription and license status
Content and Technical Data (Org Technical Lead and Team Lead)
- Archetype Specs (variation point values, entity definitions, configuration choices)
- Generated source code
- Generation summaries with content context — which Archetypes are being used, which teams and users generated which apps, current pipeline status
- AI invocation logs and decision rationale
- Governance outputs (SBOMs, provenance records, NIST AI RMF mapping, vulnerability snapshots)
- Adoption patterns — which Archetypes are used most, how generation quality trends over time
Operational metrics that appear to overlap (e.g., generation counts) are classified by what they expose. A count of generations per team (number) is operational data accessible to Org Admin. The same data with content context (what was generated, which Archetypes, what the Specs contained) is content/technical data accessible only to Org Technical Lead and Team Lead.
Spending Limit Approval Workflow
Spending limit changes follow a two-step approval workflow built into the platform dashboard — this is a platform UI feature, not an external process.
Initiation: Either the Org Admin or the Org Technical Lead can initiate a spending limit change request.
Approval: The Org Technical Lead must approve the request before the change takes effect. If the Org Technical Lead initiated the request, they can self-approve.
Execution: Once approved, the limit is applied. The Org Admin can also confirm and execute the change in the admin dashboard.
The detailed UI design and notification flow for this workflow is specified in ADR-0033 (Operational Governance).
For MVP, all Archetypes available to an Organization are accessible to all Developers in that Organization. No team-level restriction is enforced.
The identity schema accommodates per-team Archetype restrictions (an optional archetype_allowlist at the Team level) for v1, following the phased rollout principle from ADR-0008. Not enforced until v1.
Spending Limits
Limits are denominated in currency (billing currency), not tokens. Token costs change; organizations plan in budget terms.
Three nested levels:
- Organization limit — set by Org Admin on authorization from Org Technical Lead
- Team limit — set by Org Admin or Team Lead, must be ≤ organization limit
- User limit — set by Org Admin or Team Lead, must be ≤ team limit
Limits are optional. No limit = no notifications, tracking only.
When a contract-based limit is set (e.g., $1M/year):
- Default 80% threshold notification sent to Org Admin AND Platform Admin
- Threshold is configurable
- At 100%: generation blocked, Org Admin and Platform Admin notified, Org Admin raises the limit to resume
Both dashboards show spend: Customer’s observability dashboard and Almathal’s platform dashboard show real-time spend. Tracking always happens; limiting is optional.
Rationale
Six roles, not five because two conflations were initially present: Platform Admin and Org Admin are different people at different scopes, and Org Admin and Org Technical Lead are different people with different needs within the same organization. Collapsing either pair produces a role that either has too much access (the infra person seeing all Specs) or too little (the senior architect unable to see what’s being built).
Org Admin does not see generation content because their job is platform administration, not platform adoption oversight. Giving the IT admin access to all Specs and generated code violates least-privilege and exposes business-sensitive data model details to a role that has no need for them.
Org Technical Lead has no administrative capabilities because separating content visibility from administrative control is a security principle — the person who sees the most content should not also be the person who manages user access. These capabilities belong to different principals.
Auditor sees generated code because verifying that the shipped code matches the SBOM and provenance records is a legitimate compliance activity. Read-only access to generated code is the minimum necessary for that verification.
Developer cannot see another Developer’s Spec because Specs contain variation point values — entity names, data model structure, configuration choices — that are business-sensitive. Code (once shared by a Team Lead) is appropriate for peer review; configuration is not.
Break-glass for Platform Admin because both extremes are wrong — unrestricted access violates customer privacy; no access at all makes support impossible. Break-glass with full logging and customer notification is the industry-standard balance.
Currency-denominated limits because token costs change over time, organizations think in budget terms, and Almathal’s value proposition is cost efficiency. Limiting by tokens would impose a platform implementation detail on organizational financial planning.
Consequences
- The Spec schema records the generating user’s ID for access control scoping
- The observability layer implements six role-based views
- The audit trail is queryable by Organization (Org Technical Lead, Auditor) and by Team (Team Lead)
- SSO configuration is an Org Admin capability; SAML/OIDC federation at the organization level is required
- The Composer checks spending limits before Stitching begins (per-user → per-team → per-org)
- Break-glass access logging is a platform-level immutable audit trail separate from customer audit trails
Open Questions (Deferred to ADR-0032 and ADR-0033)
ADR-0032: Who owns a generated artifact; how artifacts are shared; what happens when a user leaves.
ADR-0033: SSO configuration detail; user offboarding procedures; audit trail retention policy; organization-level security policy configuration.
References
- ADR-0028: Almathal AI Governance Posture — audit trail and observability architecture that RBAC is applied to
- ADR-0029: Customer AI Governance Outputs — governance package the Auditor role accesses
- ADR-0030: Stitcher Security Invariants — Invariant 8 (generation isolation is the multi-tenancy guarantee RBAC sits on top of)
- ADR-0008: Adapter Slots with Capability Contracts — phased rollout principle applied to Archetype access control