This is the decision record as it was written, grilled and shipped. It’s copied from our repository unedited, apart from customer, partner and bank names, which read [redacted]. It was written for the people and agents building the product, so expect internal shorthand, and the mistakes are left in.

ADR-821: External machine identity and institution connections

Status: Shipped — 2026-09-30

The platform half of ADR-694, carved out so that two series can stand on it without either waiting for the other: the corporate banking stream (statement ingest, ADR-694) and the cards stream (the processor seam, ADR-820).


Outcome

External systems now authenticate as machine principals registered on the platform, and each tenant configures institution connections that pin which client may act for it; the gateway resolves a machine token to a tenant and connection frame, and refuses /api/auth/* (F-1566, landed earlier and kept). Outside development the machine path refuses every bearer until the Entra issuer and audience are configured, and one authored test is skipped because a settings command’s four-eyes action is settings.publish.

Context

The Problem

Two ADRs need the same three things and neither is built. ADR-694 D13 declares an InstitutionConnection settings row for every institution we exchange with; D18 chooses OAuth2 client credentials as the first machine-to-machine identity, the pattern every later external system inherits; and its bite 14 adds IExternallyAuthenticatedCommand, the marker that keeps a machine’s command out of four-eyes. ADR-820 reuses all three for a card processor and, as written, waits on ADR-694’s fourteen bites for the two it needs.

ADR-694 also left one gap that both consumers hit: it keeps the OAuth client id on the per-tenant connection row, but an inbound token has to resolve its tenant before any tenant settings can be read. Nothing says how a client id maps to a tenant (F-1562).

The platform has no machine identity of any kind today. Every endpoint is user-authenticated through the gateway (ADR-067, ADR-376 D9) or [PublicEndpoint]. The one unattended caller, provisioning, carries a service token minted with the System identity and no tenant.

What Already Exists

Scope

This ADR covers:

Out of scope: any statement ingest (ADR-694 keeps the delivery, the doors, the readers and the provisional ledger); any card contract (ADR-820); mTLS (layerable at the gateway later, as ADR-694 D18 says); rotation of the IdP secret (the IdP’s).


Decisions

1. InstitutionConnection is a tenant settings row with a generic core, and features attach facets keyed by it

The row is ADR-694 D13’s, moved here: key, institution name, BIC, and transport (a name and whether it can stream). Nothing about statements, feeds or cards is on it, and the IdP client id is not on it either: which application speaks for a connection is the machine principal’s fact (Decision 2), and a second copy on the row would be two answers to one question. The list query shows the enabled principals beside each row instead. A feature that needs more declares its own settings row keyed by InstitutionConnectionId: ADR-694’s feed authority, intraday style and formats become a statement facet it owns; ADR-820’s processor kind, environment, base address and decision budget are already such a facet.

Why a core and facets, not one wide row. The cards ADR and the statements ADR each add fields the other never reads. One wide row is a bool per product on a shared type, the signal CLAUDE.md names for a shared concept about to drift.

Commands are ADR-694 D21’s, moved here with their keys: AddInstitutionConnectionCommand, AmendInstitutionConnectionCommand, RemoveInstitutionConnectionCommand, each ISettingsCommand<InstitutionConnectionSettings> under connectivity.*.

Removal is refused while anything names the connection, by the validator. The settings handler cannot see the facets, which live in other feature projects, so each feature registers an IInstitutionConnectionFacet naming the facet it holds for a connection, and the remove command’s validator asks every one, and asks IMachinePrincipalReader whether an enabled principal still speaks for the connection, because a token minted with a connection claim that no settings row explains is a claim an auditor cannot resolve. It is a validator rule and not a handler check because the settings commands are four-eyes eligible: a handler check would refuse only after a checker approved, while a validator refuses the maker at once and re-runs at approval (ADR-780 D9). The settings page lists facets and principals under each connection.

2. A machine principal is a platform record binding one client id to one tenant and one connection

The IdP authenticates the caller and says only which application it is. Which tenant that application may enter, and which connection it speaks for, is ours to say, and it must be answerable before any tenant settings are read. So it is a platform-level record beside the platform User: MachinePrincipal in LedgerTM.Identity on the platform store, keyed by the IdP client id, holding the tenant, the connection key, and whether it is enabled.

One principal, one tenant, one connection. A processor serving two of our tenants is two registered applications at the IdP and two principals here. Registering a client id that is already registered, for any tenant, is refused. The alternative, one principal with a list of tenants, needs the token to say which tenant it means on each call, and a stolen credential then reaches every tenant on the list. ADR-694 D18 bounded a credential’s blast radius to one institution’s accounts; this bounds it to one tenant first.

A principal holds no grants, and it holds an actor. What a connection may dispatch is derived from the catalogue (Decision 5), never stored on the principal. What it does hold, beside the client id, the tenant and the connection, is a UserId minted at registration, the way a platform User holds one, so that every event a connection causes is attributed to an actor the audit trail can name without a machine masquerading as a person or as the system. Two events: MachinePrincipalRegistered, MachinePrincipalRevoked. Revocation is soft: the record is listed as revoked, and registering the same client id for the same tenant and connection again re-enables it with a second registration event. Registering an enabled principal for the same binding is a no-op; registering a client id bound to any other tenant or connection is refused, revoked or not, because rebinding would put two tenants on one principal’s history.

Registered through platform endpoints under the platform role, never by tenant settings and never by YAML. The binding is a security decision about who may enter a tenant, the same class as onboarding a person, and it is taken by the role that onboards people. Register, revoke, resolve and the two list endpoints are minimal APIs beside /api/auth/resolve and the provisioning endpoints, gated by IPlatformAuthority against platform.administer, taking request records and writing the platform store through its own session as the User aggregate does. They are not Wolverine commands, for the reason the resolve endpoint already records: the platform store is not integrated with Wolverine, a Wolverine chain needs a tenant frame a platform administrator does not have, and a tenant catalogue key would let a tenant’s own administrator grant themselves the right to register a machine. No new catalogue keys, no four-eyes question, because four-eyes captures tenant commands and these are neither. There is no screen in this ADR, because there is no platform administration screen for anything yet.

The development and simulation principals are one idempotent seed step. It runs in the simulation seed phase beside SeedDevMember, registers a per-tenant client id for the sim-processor connection only where the tenant’s settings hold that row, and is safe to run again. Deleting a tenant revokes its principals, so a re-provisioned tenant does not meet its own stale binding.

Platform-level four-eyes is a recorded gap. A second pair of eyes on who may enter a tenant is worth an ADR once a second platform-level mutation appears; until then the platform role and the two events are the controls, deferred and dated in §Notes rather than pretended.

Every resolution attempt is recorded, refused ones included. The resolve endpoint writes a MachineResolutionAttempt document on the platform store for every call: the client id, the outcome (Resolved, UnknownClient, Revoked), and when. It returns the outcome and never throws, because a thrown refusal would roll the attempt back with it. A client id probing the endpoint leaves a trail the platform role can list; a refused caller has no tenant, so no tenant-scoped audit could hold it. The gateway does not proxy /api/auth/* from outside: those are its own server-side calls, and exposing them would let any signed-in person resolve any client id. That also closes the same exposure on the existing person resolve.

3. The gateway resolves a client-credentials token exactly as it resolves a person, and mints the same token

A request arriving with an IdP client-credentials bearer token is validated against the IdP (ADR-067’s discovery document, the same authority). The gateway posts the application id to /api/auth/resolve-machine; the API answers from the MachinePrincipal, or refuses. On success the gateway mints the identity token with tenant_id set to the principal’s tenant, sub set to the actor the principal holds (Decision 2), email set to the client id, and a new connection claim naming the connection key; the principal id derives from the client id. The API reads identity from that token and nothing else, as ADR-376 D9 requires; no new header, no new signing key.

The gateway caches a resolved principal per client id for sixty seconds. A processor asks for an authorisation many times a second and a revocation happens once a year; resolving on every call would spend a share of ADR-820’s decision budget on a question whose answer does not change. A revoke therefore takes effect within a minute, which is shorter than the IdP token’s own life. The cache holds refusals for the same sixty seconds, so a probing client id costs one resolve a minute.

A development machine-token endpoint stands in for the IdP, and only there. The gateway issues a client-credentials-shaped token for a registered development or simulation principal when the environment is Development or Testing, and refuses the endpoint anywhere else, the same check ADR-376 put on the dev login. It stands in for token issuance only: the request still goes through resolve-machine, the cache and the mint, so the whole path runs in development and in the gateway tests.

The machine path runs first, and validates what a bank’s security team expects. The machine middleware reads the bearer before the gateway strips inbound authorisation headers and before either person middleware, and short-circuits: a bearer is a machine, a cookie is a person, and a request carrying both is a machine. The issuer is pinned to our own Entra directory and the audience to the API’s application id, so an application in any other directory cannot present a token; the client id is read from the v2 azp claim, falling back to v1 appid. A development token is signed with the gateway’s own identity signing key under a distinct audience, so the API refuses it as an identity token, and it is accepted only where the development login is, so it never validates against the discovery document and never exists outside Development and Testing. The cache is in memory per gateway instance; there is one instance today, and a second would each hold a revocation for at most sixty seconds.

Why resolve through the API rather than the gateway holding the map. The gateway holds no data of its own today; the person path already resolves through the API, and a second store in the gateway would be a second answer to “who may enter this tenant”.

4. On the API the caller is a connection, and the lock lets it through

The identity frame gains an origin, Person, System or External; the existing SystemOriginated flag becomes derived from it so nothing that reads the flag changes. IdentityFrame.ForConnection(tenant, actor, principal, connection) has origin External, its actor is the UserId the principal holds (Decision 2), its email is the client id, and it carries the principal and the connection, which ICurrentConnection exposes to a handler that needs them. A message that implements IConnectionScoped and names a different connection than the frame’s is refused before its handler; a frame with no connection binds nothing, so a person or the system may dispatch a connection-scoped message. ADR-694 D18’s rule that a connection may report only on its own institution’s accounts is the first instance. Whoami answers from the frame, never from settings: the connection key from the claim, its id derived, the client id from the frame’s email.

The connection frame holds for the first hop only. A message the API publishes is dequeued into a system frame, so a cascade runs as the system and ICurrentConnection is empty there. This ADR states that and stops; whether origin and connection travel as envelope headers is ADR-694’s and ADR-820’s to decide when a cascade needs them.

The day-end lock lets an external origin through. ADR-142 refuses a person’s mutation while day-end runs and passes a system-originated one. An external system cannot wait for our day-end: a processor’s authorisation must be answered now, and a bank’s push arrives when the bank sends it. So the lock passes System and External, and the receiving feature decides what an external act may touch during day-end. ADR-694 holds a pushed entry provisional; ADR-820 writes to a stream day-end does not hold. Refusing at the lock would turn every day-end into a processor outage.

5. What a connection may dispatch is derived from the catalogue, and no human can be granted it

IExternallyAuthenticatedCommand marks a command dispatched by an authenticated non-human principal. Eligibility becomes ICommand && !ISystemCommand && !IFourEyesControlCommand && !INotFourEyesGated && !IExternallyAuthenticatedCommand: neither ISystemCommand, which means UserId.System, nor eligible, because a bank’s push or a processor’s authorisation cannot wait for an approver.

The catalogue carries the kind, so queries are covered too. Every permission key is still catalogued (ADR-118), and a key has a kind: Human, SystemInternal or ExternallyAuthenticated, held as a second set beside the existing system-internal one. The kind is data, so the grant handler reads it: UserGroup.GrantPermissions refuses an externally authenticated key for a human role, and the whoami query, which carries no command marker, is refused the same way by its kind.

One rule answers what a frame may hold, and both permission paths call it. A connection frame is permitted every externally authenticated key and no other; a person frame is permitted no externally authenticated key, even a tenant administrator who otherwise holds everything. That rule is one static function over the origin and the kind, called by the HTTP permission middleware and by the bus authorisation middleware before either consults a person’s grants, because a principal has no member record to hold grants and a person’s wildcard must not reach a machine’s key. Deny-by-default holds in both directions with nothing stored on the principal.

A marked command in a person frame is refused before its handler; in a system frame it runs, because a cascade after the first hop is a system frame (Decision 4) and refusing there would refuse every marked command’s own follow-on work. The architecture tests gain three checks: every command carrying the marker has a catalogue key of the matching kind, every key of that kind names a type carrying the marker or an IQuery<T> pinned to that key, and the four-eyes derivation carries the fifth term (the fourth, INotFourEyesGated, is ADR-780’s).

6. The path is demonstrable with nothing above it

GET /api/connections/whoami, a query under connectivity.whoami of the externally authenticated kind, answers the tenant, the principal and the connection the caller resolved to. A registered simulation principal, a token from the development machine-token endpoint, and that endpoint are a two-minute demo.

Proof runs on both sides, and the rules with no production subject are proven as rules. The component suite proves the API side by minting the identity token with the signing key, the service-token precedent, and calling the API: the frame, the whoami answer, the grant refusal. The lock rule, the marker rule and the other-connection refusal have no production command in this ADR to carry them, and a query passes the lock before identity is read, so they are proven as unit tests over the middleware with a stubbed frame and message. The gateway suite in LedgerTM.Tests/Gateway proves the gateway side through the development machine-token endpoint: resolve, the sixty-second cache with a fake clock, the mint, a revoke taking effect after the cache expires, and the proxy refusal. Every later external system inherits these tests.


Contracts

Ids — InstitutionConnectionId (slug-derived, ADR-422), MachinePrincipalId (name-derived from the client id).

Contract types — all in LedgerTM.Infrastructure.Contracts, because the identity frame and the middlewares live there and LedgerTM.Contracts depends on it, not the reverse. Namespace LedgerTM.Contracts.Connectivity (the precedent is LedgerTM.Contracts.Authorisations, already in that project): InstitutionConnection (key, name, BIC, transport), ConnectionTransport (name, streaming capable), IInstitutionConnectionFacet, IInstitutionConnectionReader, IMachinePrincipalReader (enabled principals, and the actor a connection frame runs as), IConnectionScoped. Namespace LedgerTM.Infrastructure.Contracts.AccessControl: IExternallyAuthenticatedCommand, PermissionKind, IdentityOrigin, IdentityFrame.ForConnection, ICurrentConnection, PermissionCatalog.PermitsFrame, the connection token claim.

Settings — InstitutionConnectionSettings (tenant vocabulary, in LedgerTM.Infrastructure).

Commands — AddInstitutionConnectionCommand, AmendInstitutionConnectionCommand, RemoveInstitutionConnectionCommand — ISettingsCommand<InstitutionConnectionSettings>, keys connectivity.add-institution-connection, connectivity.amend-institution-connection, connectivity.remove-institution-connection.

Platform endpoints (minimal APIs in LedgerTM.Identity, gated by IPlatformAuthority against platform.administer; not commands) — register a machine principal, revoke one, list them, list resolution attempts; and POST /api/auth/resolve-machine, unauthenticated like its person sibling, answering an outcome and never throwing.

Events — MachinePrincipalRegistered, MachinePrincipalRevoked (on the MachinePrincipal aggregate in LedgerTM.Identity, platform store).

Read documents — MachineResolutionAttempt (platform store: client id, outcome Resolved | UnknownClient | Revoked, when).

Queries — ListInstitutionConnectionsQuery (key connectivity.list-institution-connections; rows with attached facets and enabled principals), ConnectionWhoAmIQuery (key connectivity.whoami, kind ExternallyAuthenticated; answers tenant, principal id and client id, connection id and key), ListPermissionsQuery gains the kind.

Consumed — IdentityToken and IdentityTokenIssuer (ADR-376 D9), IPlatformAuthority, FourEyesEligibility, PermissionCatalog, SystemLockMiddleware (ADR-142), AuthorizationMiddleware, HttpPermissionMiddleware, UserGroup.GrantPermissions.

Changed — FourEyesEligibility.IsEligible gains the fifth term; IdentityToken gains the connection claim; IdentityTokenIssuer.Mint gains the connection; IdentityFrame gains Origin, Principal and Connection with SystemOriginated derived; PermissionCatalog gains ExternallyAuthenticatedKeys, KindOf and PermitsFrame, and IsGrantable reads the kind; UserGroup.GrantPermissions refuses an externally authenticated key; HttpPermissionMiddleware and AuthorizationMiddleware call PermitsFrame; the gateway refuses to proxy /api/auth/*; ForbiddenException gains a constructor taking the key and a message, so a refusal can name the marker or both connections; ISystemCommand’s summary names PermissionCatalog.KindOf.

Removed — none. ADR-694 D13, D18, D21 and bite 14’s marker are superseded by reference: its plan shrinks to the statement facet, the push door and the readers.


Prior art

python3 scripts/adr/prior_art.py --concept "external machine identity client credentials institution connection tenant resolution client id" returned no ADR title and three proposal documents. The candidates below come from ADR-694, ADR-376 and the AccessControl folder.

Declared Search returned Verdict
InstitutionConnection, InstitutionConnectionId, ConnectionTransport, InstitutionConnectionSettings, AddInstitutionConnectionCommand, AmendInstitutionConnectionCommand, RemoveInstitutionConnectionCommand, ListInstitutionConnectionsQuery ADR-694 D13, D21 and its plan’s record shape, Proposed, unbuilt reuse, moved — the generic core keeps ADR-694’s names; feed authority, intraday style and formats leave for a statement facet ADR-694 owns
IExternallyAuthenticatedCommand ADR-694 bite 14 (F2); IUnauthenticatedCommand means the opposite (no principal at all); ISystemCommand means UserId.System reuse, moved — the same marker, decided once here
MachinePrincipal, MachinePrincipalId, MachinePrincipalRegistered, MachinePrincipalRevoked, the register and revoke endpoints the platform User aggregate in LedgerTM.Identity with UserExternalLookup (a person keyed by IdP identity); ServiceTokenIssuer (ADR-376 D9, the System identity for provisioning); ProvisioningEndpoints and ApproverCredentialEndpoints (minimal APIs on the platform store under IPlatformAuthority) genuinely new for the principal, reuse the pattern for the endpoints — a non-human principal bound to one tenant and one connection; a User is a person with memberships, and the service token has no tenant by design
/api/auth/resolve-machine /api/auth/resolve for a person, a minimal API because the platform store is conditionally registered and Wolverine.HTTP code-gen would fail extend the pattern — same step, same shape of endpoint, a different subject; its own endpoint because the answer differs (one tenant, never a list)
IdentityFrame.ForConnection, External origin, ICurrentConnection IdentityFrame.ForUser, IdentityFrame.SystemActingAs (ADR-728), ICurrentUser extend — a third frame kind; the lock’s origin rule gains one value
connection token claim tenant_id, sub, platformRole claims on IdentityToken extend — one claim; no new header, no new key
FourEyesEligibility (the fifth term) IFourEyesGate, FourEyesChainScope, INotFourEyesGated (ADR-780: a command a checker cannot read) extend — one more term in the existing derivation; INotFourEyesGated answers a different question (reviewable or not), and a machine’s command is excluded for who dispatches it, not for what a checker could read
ISystemLockState (the External origin) SystemLockMiddleware, ISystemLockExempt, SystemLockedException (ADR-142) extend — the lock already reads an origin and already exempts the system; External is one more value it passes, and ISystemLockExempt per command was rejected because every externally authenticated command would carry it
IdentityTokenIssuer (the connection claim) IdentityToken (ADR-376 D9: the claims the gateway mints) extend — one claim on the same token, same key, same audience
IInstitutionConnectionFacet, IInstitutionConnectionReader, IMachinePrincipalReader IAuthorisationApprover (ADR-728), IApproverViewReader (ADR-780): Contracts seams a feature implements so another may ask it reuse the pattern — the settings handler asks every feature what names a connection, without referencing any
IdentityOrigin IdentityFrame.SystemOriginated (a boolean; ADR-728 reads it, SystemLockMiddleware reads it) extend — three values replace a boolean; the boolean stays, derived, so no reader changes
PermissionKind, PermissionCatalog.PermitsFrame SystemInternalKeys, IsSystemInternal, IsGrantable (ADR-197); PermissionService.HasAsync read by both middlewares extend — a second key set and KindOf over both; PermitsFrame is one static rule both middlewares call before a person’s grants are consulted, so the wildcard never reaches a machine’s key
MachineResolutionAttempt RecordAccessSessionStartedCommand (ADR-340: a person’s session on the tenant store) genuinely new — a refused caller has no tenant, so the attempt lives on the platform store; the person’s access audit cannot hold it
ConnectionWhoAmIQuery MyProfileEndpoint, MeFeatures (a person’s view of themselves) genuinely new — a machine’s view of what it resolved to

Relies on

Symbol What it does today What this ADR assumes
IdentityTokenIssuer.Mint Mints the gateway’s signed token for a person Gains a connection claim; the same key and audience
OidcService (ADR-067) Reads the IdP’s discovery document Validates a client-credentials token against the same authority
/api/auth/resolve Resolves a person to the tenants they may enter The machine resolve step is its sibling
FourEyesEligibility.IsEligible Four-term derivation (ADR-197, ADR-780) Gains the fifth term
IPermissionCatalog and PermissionCatalogTests Every command’s key is declared by its module (ADR-1200) The marker sets the key’s kind
SystemLockMiddleware (ADR-142) Passes a frame whose SystemOriginated is true Passes origins System and External
UserGroup.GrantPermissions (ADR-118) Grants catalogue keys to a role Refuses a key whose catalogue kind is externally authenticated
ISettingsCommand<T> and SettingsCommandMiddleware Loads and saves a settings root around a handler The three connection commands
IPlatformAuthority and RequirePlatformAuthority (ADR-376 D1) Gates a minimal API on platform.administer The five platform endpoints
HttpPermissionMiddleware and AuthorizationMiddleware Consult a person’s grants through PermissionService Both call PermitsFrame first
SeedDevMember Registers a development person at provisioning Registers the development and simulation principals the same way

Worked example

Fixture: the za-retail tenant (package retail-bank), simulation on; a connection sim-processor in its InstitutionConnectionSettings with transport ProcessorApi; a machine principal registered by the platform administrator binding IdP client id app-sim-za to tenant za-retail and connection sim-processor; the test IdP double issuing client-credentials tokens.

Row Before After
Register principal app-sim-za → za-retail / sim-processor none MachinePrincipalRegistered; the platform lists it enabled
Token for app-sim-za calls whoami — tenant za-retail; principal id and client id app-sim-za; connection id and key sim-processor
A tenant administrator holding every role calls whoami — refused: a person frame is permitted no externally authenticated key
Token for app-sim-za calls whoami during day-end on za-retail lock held answered; the lock passed the External origin
Token for an unregistered client id calls whoami — refused at resolve; nothing minted; a resolution attempt records the client id with outcome UnknownClient
Revoke app-sim-za, then call whoami within sixty seconds enabled answered from the cache
Call whoami again after the cache expires revoked refused at resolve; the attempt records outcome Revoked
A person holding every role tries to grant connectivity.whoami to a role — refused: the key is externally authenticated and not grantable to a human
A command marked IExternallyAuthenticatedCommand is dispatched by a person’s frame — refused before the handler: the marker requires a connection frame
Remove sim-processor while a facet (ADR-820’s processor settings) still names it facet attached refused naming the facet
Remove sim-processor with no facet, while principal app-sim-za is enabled for it principal enabled refused naming the principal; removable once it is revoked

Model

Generated from docs/model/model.json (ADR-773 D8): the shape the model knows today, <<new>> for what ## Contracts declares and the model does not know, relies-on for ## Relies on. Regenerate with python3 scripts/model/adr_model.py ADR-NNN --write; frozen at Shipped.

classDiagram
  class User {
    <<aggregate>>
    String Email
    String ExternalId
    UserId Id
    Boolean IsActive
    String Name
  }
  class UserGroup {
    <<aggregate>>
    UserGroupId Id
    String Name
    String Permissions
    String RoleKey
    TenantId TenantId
    GrantPermissions() «relies-on»
  }
  UserGroup ..> UserGroupPermissionsGranted : GrantPermissions
  class UserGroupPermissionsGranted {
    <<event>>
  }
  class Connection {
    <<new>>
  }
  UserGroup ..> Connection : declared
  class ExternallyAuthenticated {
    <<new>>
  }
  UserGroup ..> ExternallyAuthenticated : declared
  class ExternallyAuthenticatedKeys {
    <<new>>
  }
  UserGroup ..> ExternallyAuthenticatedKeys : declared
  class IsGrantable {
    <<new>>
  }
  UserGroup ..> IsGrantable : declared
  class KindOf {
    <<new>>
  }
  UserGroup ..> KindOf : declared
  class Origin {
    <<new>>
  }
  UserGroup ..> Origin : declared
  class PermitsFrame {
    <<new>>
  }
  UserGroup ..> PermitsFrame : declared
  class Principal {
    <<new>>
  }
  UserGroup ..> Principal : declared
  class Resolved {
    <<new>>
  }
  UserGroup ..> Resolved : declared
  class Revoked {
    <<new>>
  }
  UserGroup ..> Revoked : declared
  class SystemOriginated {
    <<new>>
  }
  UserGroup ..> SystemOriginated : declared
  class UnknownClient {
    <<new>>
  }
  UserGroup ..> UnknownClient : declared
  class FourEyesEligibility {
    <<relies-on>>
  }
  class HttpPermissionMiddleware {
    <<relies-on>>
  }
  class IPlatformAuthority {
    <<relies-on>>
  }
  class IdentityTokenIssuer {
    <<relies-on>>
  }
  class OidcService {
    <<relies-on>>
  }
  class PermissionCatalog {
    <<relies-on>>
  }
  class SeedDevMember {
    <<relies-on>>
  }
  class SettingsCommandMiddleware {
    <<relies-on>>
  }
  class SystemLockMiddleware {
    <<relies-on>>
  }

Consequences

Positive

Negative / Trade-offs

The cheaper option, and why not

Leave all of this in ADR-694 and build ADR-694 first. No new ADR, no reconciliation. Refused because the cards series would wait on twelve bites of statement ingest for two of platform identity, and because the client-id-to-tenant gap would be found again at ADR-694’s bite 14 rather than decided now.

Neutral


Implementation Plan

Four bites, one land. Bites, acceptance criteria, files touched, interfaces, scenarios and status live in ADR-821-plan.md.

Notes


Changed during the grill

Grilled 2026-09-30 against the code, the same day as drafting. What the draft said, what it says now, and why.

Pressed and held without change: the row’s generic core with feature facets; one principal per client id per tenant per connection, with a second tenant refused; resolving through the API rather than a map in the gateway; the same identity token with one added claim; the lock passing an external origin; IExternallyAuthenticatedCommand as the fourth term; the out-of-scope list, with mTLS and secret rotation held as the IdP’s and the gateway’s.

Contradiction press: 6 pairs, resolved as listed above. Run by a fresh agent given the decisions and the worked example only. Its returned block, condensed:

  1. A principal “holds” keys but has no field or event for grants — resolved: derived from the catalogue kind; nothing stored.
  2. The whoami query’s grant is refused by a rule that fires only on a command marker — resolved: the catalogue kind covers queries.
  3. A connection can be removed while a principal still speaks for it — resolved: refused through IMachinePrincipalReader.
  4. The revoke-within-sixty-seconds claim has no test on either side — resolved: the gateway test forces cache expiry; the dev endpoint runs the real resolve.
  5. Register and revoke are four-eyes eligible by the derivation with no approver view — resolved: INotFourEyesGated with the reason; platform four-eyes deferred and dated.
  6. A refused resolve leaves no record — resolved: MachineResolutionAttempt on the platform store.

Changed during the plan grill

Plan grill 2026-09-30 (phase A questions from the test author, then a fresh reader over the signatures). What the ADR said after the design grill, what it says now, and why.