System overview and trust boundaries

Ten minutes to understand where GenAuth sits in your architecture: five parties, three trust domains, and what makes each cross-boundary call trustworthy. This page is not about sequence — that lives in End-to-end sequence. It is about static structure. When you review the architecture, start with this diagram.

One diagram: five parties and three trust domains

The three dashed boxes are the three trust domains:

• Your trust domain: your app, your resource services, the agents you run. Business data is produced and consumed here.
• GenAuth trust domain: the authorization plane. In the SaaS model it is hosted at api.eak.eazo.ai; in the self-hosted model the whole thing is deployed into your Kubernetes environment, in the same domain as your Human IAM (for the differences, see Deployment models).
• Existing identity trust domain: the enterprise identity system you already run (Human IAM). The authoritative source for who a person is and what they really may do lives here, and GenAuth does not replace it.

One architectural position, stated up front: GenAuth is the authorization plane, not the data plane. When an agent accesses a resource, the traffic goes agent → your API directly. Business data never passes through GenAuth — its only job is to answer "what makes this access allowed".

What each of the five parties owns

Party	Role	Responsibility in one line
User (employee / end user)	The source of authority	Every ounce of power an agent exercises is explicitly handed over by a person
App (your app and resource services)	Business entry point + resource-side gatekeeper	Starts delegations; performs the final access token check on the resource side
Agent	The actor	Holds only short-lived, attenuated tokens; never holds a person's original credentials
GenAuth	Authorization plane	Registration, consent, issuance, exchange, audit, revocation
Human IAM	Authoritative source for identity and permissions	Answers "who is this person, and what do they really have"

Every trust assumption, one by one

An architecture review cares less about "which components exist" than about "who trusts whom, and on what basis". Here they are, one at a time.

Resource services trust the token, not the agent

Your resource services never need to know a particular agent, and never share a secret with one. What they trust is the token itself, on three grounds:

• Signature: the token is a JWT issued by GenAuth and verified with GenAuth's public key. It cannot be forged.
• Audience binding: an exchanged access token has its aud bound to a specific target resource, so it is worthless elsewhere — if a token is stolen, the blast radius is nailed to a single resource.
• Scope intersection: the scopes in the token are the result of attenuation. Every hop narrows; no hop widens.

The obligation on this side of the boundary: the resource side must explicitly validate all three of sub (on whose behalf), act (which actor), and scope (what is allowed). Check sub without act and attenuation becomes decoration. For the checklist see Protect your APIs: resource-side integration; for the field contract see Token and claim reference.

GenAuth trusts your server, on the strength of AK/SK

Starting a delegation is a server-side action: your app authenticates to GenAuth with a tenant-level access key (AK/SK). This is the only long-lived credential in the whole system, which is why it carries the strictest constraints — server side only, never in a browser, never inside an agent, with rotation and immediate revocation supported.

The obligation on this side of the boundary: hold AK/SK under your own secret management policy, and the moment you suspect a leak, rotate first and investigate second.

Nobody trusts an agent's own claims about itself

An agent saying "I can read customer reports" counts for nothing. Its permissions are not self-declared; they are decided by three external sets: the person's real permissions ∩ the explicitly delegated scope ∩ the organization's approved boundary. The Delegate Token an agent receives records the result of that intersection, and every subsequent token exchange can only narrow further inside it.

The corollary matters: the agent side needs to hold no long-lived credential at all. Tokens are short-lived, attenuated, and recallable, so when an agent is compromised the most an attacker walks away with is an authorization slice that is about to expire. For the mechanism, see Delegate Token and attenuation.

The user's intent is expressed explicitly, through consent

GenAuth does not decide for the user. The consent screen states three things — which agent, what scope, for how long — and the authorization only exists once the user confirms. "The human decides" shows up in two forms:

• User-level consent: the end user agrees in person on the consent screen (the interactive main line).
• Organization-level consent: an administrator agrees in advance on the organization's behalf, through the trusted server-side path.

Both leave an audit trail, both can be withdrawn, and the worldview does not change: authority always originates from a person. For details, see Consent and approval.

GenAuth toward Human IAM: read, never write

Permissions originate in the Human IAM you already run. GenAuth performs evaluative reads only — "what does Alice really have" — and never writes to or migrates your user directory. In the self-hosted model that constraint becomes three hard rules: a dedicated read-only account, a fixed read-only view, and an audit record for every read (see the authentication matrix in Deployment models).

Every agent has a human behind it: the accountability assumption

Anonymous agents are not allowed to exist. Registration binds two accountable humans: the Owner handles development, configuration, and credential rotation; the Sponsor answers "whose books does this agent land on". When something goes wrong, the audit chain does not end at a service account — it ends at a person who can be held accountable. For the model, see The agent identity model.

What these boundaries prevent

• The blast radius of a leaked credential: agents hold no long-lived credentials, and tokens are short-lived plus audience-bound. A stolen token cannot move laterally; waiting for it to expire is waiting for it to die.
• Confused deputy: an access token names the real actor in act, and the resource side validates it explicitly, so an agent cannot pose as "the user in person" and fool a downstream service.
• Delegation beyond authority: the three-way intersection guarantees "you cannot delegate a permission you do not have" — a user cannot hand over authority they lack, and anything outside the organization's boundary is cut.

For the full threat model, including token theft and the dual-track compatibility window, see Security considerations.

Next steps

• Deployment: SaaS or self-hosted same-domain sidecar, and where the data boundary falls → Deployment models
• How the five parties interact on a timeline: the full 7-hop / 8-hop sequence → End-to-end sequence
• The complete threat model and hard security constraints → Security considerations