EN

中文

EN

中文

Appearance

Go to Dashboard
中文

🧪 Beta — Available today; the interface contract may still change.

Consent and approval ​

Consent is the one step in a delegation system that cannot be automated: a human has to decide.

But "a human decides" happens at three different moments, which map to three different product shapes and three different risk profiles. Telling them apart is the prerequisite for designing an authorization experience that is both safe and not annoying.

Why an agent needs it ​

Without consent, delegation is just "the system decided for you." Three consequences follow immediately: the user doesn't know what permissions the agent took (not explainable), compliance can't get an answer to "who approved this" (not accountable), and after an incident there's no way to draw the line of responsibility (whose fault is it).

Consent isn't solving a technical problem. It solves an attribution problem: making every agent permission point back to a person who made a decision.

Three moments where a human decides ​

MomentWho consentsWhen to use itCost
User-level consentThe end user clicks approve in personData and operations belonging to a specific individualRequires the user to be present; costs an interaction round trip
Organization-level consentAn org admin consents in advance on the organization's behalfBackground jobs, first-party apps with a mature login systemThe key is the power, so hardening requirements are high
Runtime asynchronous approvalSomeone is found on the spot when a specific operation firesSensitive, irreversible, high-value operationsInterrupts automation; needs an approval channel

The most direct form: whatever the agent wants, the user approves it while watching.

The user is taken to a consent page and sees three things clearly — which agent, which permissions, for how long — then approves, gets redirected back, and your application exchanges for a Delegate Token. The whole flow is in Steps 2–3 of the Quickstart.

How it works (with responsible parties):

  1. Your application starts a delegation request to GenAuth (mode: "interactive"), declaring the agent, scopes, lifetime, and redirect URI.
  2. GenAuth returns the consent page URL and records a pending authorization record.
  3. The user authenticates on the consent page and makes a choice. Where that identity comes from depends on how you integrated (see Integration principles).
  4. GenAuth verifies that the approver really is the authorized user, then issues a one-time callback code (void once consumed).
  5. Your application exchanges the code for a Delegate Token and receives grantId and audit_id.

The one-time code, the approver identity check, and the redirect state check are the three things that stop an authorization from being hijacked or replayed. All three are enforced on the GenAuth side.

Not every scenario has a user present: nobody is watching a nightly batch job, and an app with a mature login system doesn't want to push its users through another consent page.

Those scenarios take the trusted server-side integration path: an org admin consents in advance, on the organization's behalf, that "this class of agent in this organization may execute these scopes for this organization's users." After that, a server holding an access key initiates delegations directly, with no per-request user confirmation.

What this path really means, and its hard constraints

Organization-level consent is equivalent to authorizing on the organization's behalf: whoever holds the access key can start a delegation for a user inside the organization. Therefore:

  • The access key may exist only in a controlled server-side environment, never on a client;
  • The key's allowedScopes / allowedAgents must be configured as the minimal set — this is delegation's first gate;
  • Keep lifetimes short, use a dedicated agent identifier, and put alerting on the audit trail.

An access key leak is an organization-level risk. The full list of hard constraints and the threat analysis are in Security considerations. Before choosing this path, read Integrate your existing identity provider to decide which integration style fits you.

Both forms of consent produce an auditable, revocable Delegate Token. The only difference is who made the decision on the person's behalf. These docs do not treat organization-level consent as a back door around authorization — it is authorization, with the organization as the consenting party.

Runtime asynchronous approval ​

🚧 Roadmap — The capability described in this section is on the roadmap. The concepts and design are settled; interfaces and steps are subject to the final release.

Some operations should not be covered by any pre-authorization: moving money, deleting a batch of data, sending a customer an email you can't unsend.

The right shape for those is asking a human at runtime: the agent pauses at the critical step, reaches the responsible person over an out-of-band channel (push, IM, email), and only after approval receives authorization limited to that single operation. On the standards side this pattern corresponds to CIBA (Client-Initiated Backchannel Authentication) — a backend-initiated flow with out-of-band user confirmation, which is precisely the standard answer to "the approver isn't in the agent's session."

Design points: the approval request must state what the agent wants to do, what it affects, and why it is asking now; unanswered requests default to denial at timeout; every approval enters the audit chain on its own. The planned shape is in Async authorization: when a human must approve.

Standards and protocols ​

  • OAuth 2.1 authorization code + PKCE: the interaction basis for user-level consent.
  • RFC 8693 Token Exchange: the product of consent (a Delegate Token) is exchanged for a resource access token (see Delegate Token and attenuation).
  • CIBA (OpenID Foundation): the standard shape for runtime asynchronous approval.

Next steps ​