How AIGW works
This page explains how AIGW fits between an agent, an MCPMCPModel Context Protocol: a standard way for AI agents to call tools and data sources exposed by a server./UCP service, and a merchant, and walks through one complete request.
Architecture
The diagram has four domains:
| Domain | Components | Typical owner | Responsibility |
|---|---|---|---|
| Agent | Agent, Agent Callback | Agent developer | Discover auth, register, start OAuth, hold the AIGW access token, call MCP/UCP. |
| Proxy | UCP / MCP Proxy | Merchant or third-party MCP provider | Advertise protected-resource metadata, challenge unauthorized requests, accept AIGW tokens, redeem merchant tokens, call the merchant backend. |
| LID (AIGW) | LID AIGW, LID Token Endpoint, LID Token Vault, plus DevCon / DevAPI / DevCLI for configuration | LoginID | Agent verification and policy, user sign-in, identity verification and consent, token issuance, merchant-token acquisition, storage, and refresh. |
| Merchant | Merchant Backend, Merchant Token Endpoint, Merchant Token Exchange | Merchant | Operate the existing authorization server and APIs, define scopes, and decide how AIGW identities map to merchant users. |
DevCon is the developer console (the AIGW dashboard), DevAPI its API, and DevCLI its command-line tool. All three configure the same AccountsAccountThe top-level AIGW tenant. It owns Projects, team membership, enabled identity providers, billing, and API keys., ProjectsProjectThe isolation boundary for an integration. It holds Resources, agents and agent policy, end users, and Proxy clients., ResourcesResourceThe downstream system registered in a Project. Its kind (Token exchange or OAuth client) decides the role AIGW plays., and policies.
The request flow, step by step
The numbers match the diagram. The example is an agent searching a merchant's products on a user's behalf.
Phase 1 — The agent discovers it needs authorization
| Step | What happens |
|---|---|
| 1. prompt | The user asks the agent to do something, such as "find me running shoes". |
| 2. search product | The agent calls the merchant's MCP/UCP service with no credentials. |
2′. return 401 and resource_metadata | The MCP/UCP service refuses and points to its Protected Resource Metadata. That document names the AIGW authorization server for this merchant's Resource. |
Phase 2 — The user authorizes the agent
| Step | What happens |
|---|---|
| 3. visit URL with HTTP sig | The agent sends the user to the per-resource AIGW authorization URL, which is dedicated to this merchant. If the agent signs the request (Web Bot Auth), AIGW records that proof. If the agent has never been seen before, it can register itself first with DCR or use a metadata URL as its client_id. Agent policy decides whether this agent is approved, held, or rejected. |
| 4. authenticate and authorize | The user signs in through an identity provider enabled on the Resource. That can be passkey, phone-based identity verification, email code, or a social IdP. The user then reviews and approves the requested scopes. |
| 5. token exchange | AIGW obtains the user's merchant access and refresh token from the merchant's own authorization server. It uses a JWT bearer assertion (RFC 7523) or token exchange (RFC 8693), signed with the Resource's signing key. |
| 6. store merchant tokens | AIGW encrypts and stores the merchant tokens in the Token Vault, keyed by Project, user, and Resource. |
| 7. callback with access code | AIGW redirects the browser to the agent's callback with an authorization code. |
| 8. get LID access and refresh tokens | The agent exchanges the code, plus its PKCE verifier, at the core AIGW Token Endpoint. |
| 9. return tokens | The agent now holds an AIGW access token. It does not hold the merchant token. |
Phase 3 — The authorized call reaches the merchant
| Step | What happens |
|---|---|
| 10. search product with LID token | The agent retries the MCP/UCP call with Authorization: Bearer <AIGW access token>. |
| 11. get merchant access token | The MCP/UCP service authenticates with its own Proxy client credential. It then sends the user's AIGW token and the Resource identifier to AIGW's credential-redemption endpoint, and gets the merchant token from the vault. |
| 12. search with merchant access token | The MCP/UCP service calls the merchant backend with a normal merchant-issued bearer token. |
| 13. refresh if access token expired | When the stored merchant token is near expiry, AIGW refreshes it at the merchant token endpoint. The agent and the MCP/UCP service never handle the refresh token. |
To watch this flow on the wire, run it in the Playground. The MCP / UCP Quickstart turns it into concrete setup steps and HTTP requests.
Two tokens, two audiences
The agent and the merchant backend never see the same credential.
| AIGW access token | Merchant access token | |
|---|---|---|
| Issued by | AIGW core authorization server | The merchant's own authorization server |
| Held by | The agent | The MCP/UCP service, server-side only |
| Used for | Calling the MCP/UCP service | Calling the merchant backend API |
| Says | This user approved this agent for these scopes, verified this way (amr / acr) | Whatever the merchant AS normally issues, for the mapped merchant user. The acting agent travels alongside the user. |
| Verified with | Core AIGW JWKS | The merchant's usual validation |
Because the merchant token stays behind the MCP/UCP service, a compromised or misbehaving agent can't call merchant APIs directly. Revoking the agent or the user's grant in AIGW also cuts off access to the stored merchant credential.
Ownership models
AIGW supports two common ways to divide the work.
Merchant operates its own MCP/UCP service
The merchant owns the AIGW Account and Project, registers its Resources, creates the Proxy clientProxy clientThe server-side credential (client ID and secret) the MCP/UCP service uses to authenticate itself to AIGW. Never give it to an agent. used by its MCP/UCP service, and configures its own authorization server. See Self-operated.
A third party operates MCP/UCP for the merchant
The MCP provider owns the AIGW Account/Project and the Proxy client. The merchant still controls its authorization server and backend. The provider gives the merchant what it must trust and configure: the AIGW Resource issuer, JWKSJWKSJSON Web Key Set: a published set of public keys used to verify JWT signatures. URL, client identifier, and requested scopes. See Third-party.
This split matters for security. The MCP provider never needs the merchant's IAM admin credentials, and the merchant never needs the MCP provider's runtime server secret.
Steps 1–12 were verified end to end with the Playground, using a private_key_jwt Resource backed by Keycloak: discovery, DCRDCRDynamic Client Registration (RFC 7591): an agent registers itself as an OAuth client at runtime, with no manual setup., sign-in, code exchange, Proxy client authentication, and redemption of a Keycloak-issued merchant token. Step 13 (refresh after expiry) follows the implementation but was not observed directly.