How AIGW works
AIGW connects an agent, an MCP/UCP service, and a merchant through user authorization and server-side merchant-token retrieval.
Architecture
LID means LoginID, the provider of AIGW. The LID Token Endpoint issues AIGW tokens; the LID Token Vault stores merchant access and refresh tokens. The UCP / MCP Proxy is the service between the agent and merchant API, and the Agent Callback receives the authorization response.
| Configuration tool | What you use it for |
|---|---|
| DevCon — AIGW Developer Console | Configure AIGW in the browser using the dashboard. |
| DevAPI — AIGW management API | Manage Accounts, Projects, Resources, and policies through API requests. |
DevCLI — aigw command-line tool | Manage the same configuration from the terminal, including with Codex or Claude Code. |
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 access tokens, redeem merchant access 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. |
The request flow, step by step
The numbers match the diagram; 2′ is the response to request 2. 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 the authorization URL | The agent sends the user to the per-resource AIGW authorization URL, which is dedicated to this merchant. If the agent uses HTTP Message Signatures through 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 token and, if the merchant authorization server issues one, a merchant refresh token. 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, Resource, and the specific login (login_id). |
| 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 and the client authentication required by its registration, at the core AIGW Token Endpoint. |
| 9. return tokens | The agent now holds an AIGW access token. It does not hold the merchant access 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 access token and the Resource identifier to AIGW's credential-redemption endpoint, and gets the merchant access 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 access token is near expiry, AIGW refreshes it at the merchant token endpoint. The agent and the MCP/UCP service never handle the merchant refresh token. If it is absent or rejected, redemption returns 410 reauthentication_required and the user must authorize again. |
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; amr / acr describe the sign-in when available | Claims issued by the merchant AS for the mapped user. The merchant AS decides whether to include the acting agent and authentication context. |
| Verified with | Core AIGW JWKS | The merchant's usual validation |
Because the merchant access token stays behind the MCP/UCP service, a compromised or misbehaving agent can't call merchant APIs directly. Agent decisions, token revocation, and downstream sessions have separate lifecycles. AIGW's /api/revoke also clears grant/cache state; discovery's core revocation endpoint only revokes the token. See Credential redemption.
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 client 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, JWKS 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.