Status: Draft Implements: Tenancy Spec, which assigns identity to this document; ADR-OS-015, which makes the six OS-level human control roles canonical; Core Principles Principle 6 (humans stay above the automation layer) Authority for: who a person or a service is to the platform; how an organisation, a user and a role relate; how a role is assigned; what a credential carries and how it is issued and ended; how authority is delegated; how an approval chain is expressed and recorded; table definitions for organisations, users, role assignments, delegations, approval decisions and service principals, which are normative in § Persistence (Group H) of this spec and mirrored as Group H in Synedrix OS - Agent DB Schema. Not authority for: what an agent may call, which stays with the Tool Authorization Model; tenant isolation, which stays with the Tenancy Spec; usage counting and entitlement enforcement; the choice of identity provider product.

Overview

The canon names the humans that matter. It gives them six control roles, derived from agent escalation paths and the Responsibility Matrix. It lets a business instance own approver_role_assignments, and it has the HITL Gateway Agent route an approval request to a reviewer_role and record a reviewer_id. What it does not say is who a user is, how one becomes a holder of a role, what a credential proves, or what happens when a holder is away. ADR-OS-008 and the Tenancy Spec both defer those questions to this document.

What is derived and what is proposed

Derived from the canonProposed here, for decision
The six control roles and their derivations; the business instance owns role assignment, thresholds and secrets; approval requests carry a reviewer_role and a human decision is recorded with a reviewer; a Policy Guard block is final and no human, including the human risk owner, reverses it; HITL approval never bypasses Policy GuardThe principal types, the credential rules, the role-assignment record, delegation, the approval-chain model, separation of duties, and support access to managed tenants

Everything in the right-hand column is a proposal in a Draft. Section 10 lists what needs deciding.

1. Principals

A principal is anything the platform authenticates and records as the actor in an audit record.

PrincipalWhat it isAuthority comes from
UserA human who belongs to an organisationThe roles assigned to them (§3)
Service principalA non-human credential holder, such as a data plane’s connection to the control plane or an integrationThe scopes granted to it (§5)

An agent is not an identity principal. An agent’s authority is its registry entry (decision_scope, tools_allowed, escalation_path) and the Tool Authorization Model. This document governs the humans around agents and the services that connect the planes, and it never widens what an agent may do.

2. Organisations and users

  1. An organisation is the tenant. Creating an organisation creates the tenant record and its tenant_id (see the Tenancy Spec). There is no second organisation concept.
  2. A user is created inside an organisation and belongs to it. Every user record carries the organisation’s tenant_id and is protected by the same row-level security as any other tenant-owned record.
  3. A user may hold roles across the organisation’s business instances. Whether one person may belong to more than one organisation is not decided; see §10.
  4. A user record holds identity attributes, status (active, suspended, removed) and the identity provider subject. It holds no credentials in plain form.
  5. Removing a user never deletes the audit records that name them. The identifier remains in the audit trail, and personal attributes follow the erasure rules in the Memory Fabric Spec where those apply.

3. Roles

3.1 The control roles

The six OS-level control roles are fixed by ADR-OS-015. This document does not add one. Each is an accountability surface, not a job title.

RoleMay act on
human operatorAgent and workflow registration, edge cases not yet encoded, resumption after a timeout
human risk ownerThe active policy ruleset (the policy rules; instance thresholds stay with the business instance owner); changing the rules through a governed policy change (no human reverses a Policy Guard block)
human domain stewardOne business function’s domain-pack behaviour, KPI vocabulary and approval points
human compliance ownerAudit findings that require action, erasure initiation, retention classes
senior reviewerContested decisions and timed-out approvals
business instance ownerapprover_role_assignments, thresholds, hitl_timeout_minutes, notification_endpoints, deployment_mode, entitlement flags, secrets

3.2 Instance role names

Domain packs and business instances use their own role names, such as trading-operator. Which control roles such a name maps to, one or several, is a business-instance decision. A role name is a label for an assignment; it grants nothing the control roles do not.

3.3 Role assignment

A role assignment is a record, owned by the business instance and changed only by a business instance owner whose own assignment covers the target scope (rule 4 below). It states:

FieldMeaning
PrincipalThe user the role is assigned to
RoleOne of the six control roles, or an instance role name mapped to them
ScopeThe tenant, one business instance, or one business function within an instance (required for human domain steward)
Valid from, valid untilAn assignment may be time-bound; it ends at its end time without further action
Granted by, granted atThe business instance owner who made it
  1. An assignment never reaches across tenants.
  2. At least one business instance owner must exist for every business instance. The last one cannot be removed.
  3. Assigning or removing a role is an audited event.
  4. Who may assign, by scope. An owner whose assignment is scoped to one business instance may create, change or remove assignments only inside that instance, and may not create a tenant-scoped assignment or one for another instance. An owner whose assignment is tenant-scoped may do so anywhere in the tenant. The first tenant-scoped owner is created when the organisation is created; after that only a tenant-scoped owner can create another or an instance owner outside their own instance’s scope. Authorisation is checked against the target scope of the change, not only against the caller’s role.
  5. No gap in ownership. At every moment each business instance has at least one currently valid business instance owner. The platform rejects any change that would leave a period with none, including setting an end time, a suspension or a removal on the last currently valid owner, and including one owner’s end time arriving when no other owner’s period covers it. The last owner’s assignment must be replaced before it can end.

4. Authentication

  1. Human access is authenticated through an identity provider. The platform accepts federation from an external provider and must also run with a provider hosted inside the deployment. In Mode 3 (air-gapped) only an in-deployment provider is permitted, because Mode 3 allows no external connection beyond the accepted inbound Hookdeck path.
  2. Which provider product is used is an implementation choice and is open; see §10.
  3. The platform binds the tenant, not the provider. A token from an identity provider is validated for issuer, signature, audience and expiry. The platform then maps the provider subject to a user record it holds, and derives the tenant_id and the role assignments in force from its own membership and assignment records. It never accepts a tenant or role asserted by the provider’s token as authoritative. The credential the platform issues carries at least the subject, the tenant_id and the role assignments in force, and that tenant_id is the one the Tenancy Spec requires row-level security to trust. It is never taken from request input. A token whose subject has no membership in the claimed organisation is rejected.
  4. Credentials are short-lived and are re-validated against the current assignments. Removing a role or suspending a user takes effect without waiting for a credential to expire; the exact mechanism is open.
  5. Sessions on approval and administration surfaces require a stronger assurance than ordinary read access. The level is open; see §10.

5. Service credentials

  1. A service principal belongs to one tenant, and its credential carries that tenant’s tenant_id claim.
  2. A credential is scoped to the narrowest set of actions it needs. A data plane’s credential lets it open the outbound connection to the control plane and carry only the traffic the Tenancy Spec §5 describes.
  3. A service credential is never a user’s credential and is never shared between services.
  4. Credentials are rotatable without downtime, and a compromised one can be revoked immediately.
  5. Secret values live in the business instance’s secret store and never in a control-plane table. The control plane holds references and metadata only. The business instance owns the secrets, as the Responsibility Matrix already assigns.

6. Delegated authority

A role holder who will be unavailable may delegate their approval authority for a defined period.

  1. A delegation is a record naming the delegator, the delegate, the role, the scope and the period. It has an end time and can be revoked at any moment.
  2. A delegate must be a user in the same tenant. A delegation cannot cross a tenant.
  3. A delegation cannot grant more than the delegator holds, and it cannot be re-delegated.
  4. A delegation does not create a role assignment. It lets the delegate act as the delegator for approvals only. It does not let the delegate reassign roles, change thresholds or touch secrets, which stay with the business instance owner.
  5. A decision made under delegation records both the person who decided and the person on whose behalf, so the audit trail shows who was accountable.
  6. A business instance owner may revoke any delegation in their business instance.

7. Approval chains

A single reviewer is the simplest chain. Where a workflow needs more, its approval_requirements declare an ordered list of steps.

Step fieldMeaning
reviewer_roleThe role whose holders may decide this step
Modeany-of: one holder decides. all-of: every holder in scope decides
TimeoutAfter which the step escalates to senior reviewer and then human operator, as the HITL Gateway Agent already does
  1. The HITL Gateway Agent routes each step to holders of the step’s role in scope, captures the structured decision, enforces the timeout and returns a binding outcome. It does not interpret or override a decision.
  2. Separation of duties. A user who initiated a request cannot approve it, in any step and by any role or delegation. This is enforceable only when the approval request carries the authenticated principal that initiated it. The current HITL Gateway input carries requester_agent_id but no initiating principal, so the rule takes effect once the contract carries a requester_principal_id (see §10), and until then it is a requirement on that contract, not a check that can be run. Where a business instance has too few holders to satisfy the rule, the request escalates and does not proceed.
  3. A chain approves only if every step approves. One rejection ends the chain as rejected. A timeout at any step escalates and does not approve.
  4. A human approval is an input to execution, never a replacement for the Policy Guard. Both must pass, and a human cannot approve past a Policy Guard block, and no human, including the human risk owner, can reverse one. The remedy is a governed change followed by re-proposal as a new invocation: the human risk owner changes the policy ruleset, and the business instance owner changes instance thresholds (rule 4 above keeps thresholds with that role) (ADR-OS-018).
  5. Each decision records the deciding principal, the principal on whose behalf it was made if any, the step, the role, the rationale and the time, in the approval state and the audit trail.

8. Identity under the deployment modes

Mode and variantIdentity providerNotes
Mode 1 or 2, managedExternal federation or a provider run by Synedrix for the tenantThe control plane is pooled; the tenant_id claim is mandatory on every credential
Mode 1 or 2, self-operatedAny permitted provider, hosted in the deployment or externalA single-tenant control plane holds one organisation
Mode 3In-deployment onlyNo outbound call to an external provider

8.1 Support access to managed tenants

Synedrix staff must not reach a managed tenant’s data through an ordinary credential. Where access is needed for support, it is granted by the tenant’s business instance owner, is time-bound, is limited to the scope requested, and is audited. A standing platform role that bypasses row-level security is never available to a tenant-facing path, as the Tenancy Spec requires.

9. Conformance

CheckExpected result
A credential for tenant A is used on a record owned by tenant BDenied, with no confirmation the record exists
A role assignment is created by anyone who is not a business instance ownerRejected
The last currently valid business instance owner is removed, suspended or given an end timeRejected
One owner’s end time arrives and no other owner’s period covers itRejected when the end time is set
An owner scoped to instance A creates an assignment for instance B, or a tenant-scoped assignmentRejected
A federated token asserts a tenant_id or role that the platform’s records do not supportThe assertion is ignored; the platform’s own records decide, and a subject with no membership is rejected
A token has a bad issuer, signature, audience or expiryRejected
A role assignment passes its end timeThe role no longer applies, with no further action
A delegation names a user in another tenant, or exceeds the delegator’s role, or is re-delegatedRejected
A user approves a request they initiated, directly or through delegation, once the request carries requester_principal_idRejected; the request escalates
A chain step times outEscalates to senior reviewer, then human operator; never approves
A human approves an action Policy Guard has blockedThe block stands
A secret value is written to a control-plane tableRejected by the schema check
An air-gapped instance is configured with an external identity providerConfiguration validation fails
A decision made under delegation is read back from the audit trailBoth the decider and the principal on whose behalf are recorded

Persistence (Group H)

Normative Supabase Postgres (PG17) DDL for the identity and access control plane. These tables are tenant-owned unless noted. They co-own the Group H inventory in Synedrix OS - Agent DB Schema: this section is the source of truth for column definitions and constraints; Agent DB Schema lists the tables for the group inventory and tenant-class matrix.

Patterns match Agent DB Schema: tenant_id leads composite keys; every table has ENABLE ROW LEVEL SECURITY and FORCE ROW LEVEL SECURITY; surrogate UUID primary-key columns are assigned by the shared assign_server_uuid trigger (never by a caller-supplied value). Full RLS policy text follows the Agent DB tenant-owned (tenant_only) pattern — restrictive tenant_scope plus permissive SELECT/INSERT or FOR ALL as appropriate. Secret values never appear in these control-plane tables; service_principals.secret_ref holds a reference only.

approval_decisions is append-only: tenant roles may INSERT and SELECT only. organisations.tenant_id is never the reserved value platform.

10. Open items

  • DDL enforcement (status). Role-grant authorisation, last-owner rejection and active-delegation validation at decided_at now have normative bodies above (grant_role_assignment, end_role_assignment, check_approval_delegation). Still to specify before Identity leaves Draft: the organisation-creation path that mints the first tenant-scoped owner, delegation create/revoke procedures, and users / service_principals provisioning procedures.
  • Identity provider product. The stack already includes Supabase, which has its own auth service. Whether it, an external provider or both fit, and how that squares with a pooled control plane, is not decided here.
  • Membership in more than one organisation (§2.3). Allowing it is convenient for consultants and complicates row-level security and the credential’s tenant_id claim.
  • Assurance and session limits (§4.4, §4.5). Credential lifetime, the revocation mechanism and whether approval surfaces require multi-factor authentication are not set.
  • Separation of duties (§7.2). The rule is proposed, not derived from the canon. Small instances may find it impractical; the escalation fallback may need a defined emergency path.
  • Delegation limits (§6). Maximum delegation length and whether all-of approval steps can be delegated are not set.
  • Event names. The identity and approval events (assignment, delegation, authentication outcomes, support access) need names in the Event Taxonomy Standard. None is proposed here.
  • Contract changes. The HITL Gateway input carries requester_agent_id and no initiating principal, so separation of duties (§7.2) needs a requester_principal_id on the approval request and the workflow contract. The HITL Gateway output contract carries reviewer_id only. Recording the principal on whose behalf a decision was made, and the chain step, needs a change to the Agent Registry entry and to the workflow approval_requirements.
  • Provisioning and lifecycle (for example directory synchronisation) and SSO and SAML timing are not specified.
  • Exposure to the pooled control plane. The managed offering’s authentication surface is internet-facing and is not designed here.

Versioning

Core Principles and Canonical Reference

Decisions

  • ADR-OS-008 — Tenancy Model — Defers identity to this document.
  • ADR-OS-015 — AI-Native Organisational Model — Makes the six control roles canonical.

Specifications this document depends on

Synedrix OS · October 2026