How AIGW works

The architecture, the request flow step by step, and who owns which credential.

Checked against the Evaluation environment, Console 0.10.1 / 0.14.1, on October 19, 2026. Release status

AIGW lets an AI agent act for a user at a merchant, using the merchant's existing OAuth server, without the agent ever holding the merchant's credentials. The agent gets an AIGW token. The service the agent calls trades that token for the merchant token on its own server.

The four parties

Party	What it is	Start here
User	The person the agent acts for. Signs in and approves once.
Agent	An AI agent or app that calls tools on the user's behalf.	Build an agent
MCP or UCP service	The tool server the agent calls. Called a Proxy in the Console.	Protect a service
Merchant	Owns the user accounts, the backend API and the OAuth server.	Configure your server

Architecture

Four domains take part. The agent domain holds the agent and its callback. The proxy domain holds the MCP or UCP service. The LID domain is LoginID's AIGW. The merchant domain holds the merchant's backend and OAuth server.

The diagram as text

Components in each domain, labelled as in the diagram:

Domain	Components
Outside any domain	User
Agent domain	Agent, Agent Callback
Proxy domain	UCP / MCP Proxy
LID domain (LoginID)	LID AIGW, LID Token Endpoint, LID Token Vault, and DevCon, DevAPI and DevCLI (the developer console, API and CLI), which all connect to LID AIGW
Merchant domain	Merchant Backend, Merchant Token Endpoint, Merchant Token Exchange

Every numbered arrow, in order:

Step	From	To	What happens
`1`	User	Agent	Prompt.
`2`	Agent	UCP / MCP Proxy	Search product, without a token.
`2'`	UCP / MCP Proxy	Agent	Return 401 and resource_metadata.
`3`	Agent	LID AIGW	Visit the URL dedicated to this merchant, with an HTTP signature.
`4`	User	LID AIGW	Authenticate and authorize.
`5`	LID AIGW	Merchant Token Exchange	Token exchange to get the merchant access token and refresh token.
`6`	LID AIGW	LID Token Vault	Store the merchant access token and refresh token.
`7`	LID AIGW	Agent Callback	Callback with access code.
`8`	Agent Callback	LID Token Endpoint	Get LID access and refresh tokens.
`9`	Agent Callback	Agent	Return tokens.
`10`	Agent	UCP / MCP Proxy	Search product with the LID token.
`11`	UCP / MCP Proxy	LID Token Vault	Get the merchant access token.
`12`	UCP / MCP Proxy	Merchant Backend	Search with the merchant access token.
`13`	LID Token Vault	Merchant Token Endpoint	Refresh if the access token expired.

Step 2' is the dashed return arrow. Between steps 2' and 3 the agent reads the authorization server metadata and registers with Dynamic Client Registration. The diagram does not draw those calls; the quickstart shows them.

The request flow

Challenge and discovery

Who: Agent and service. Diagram steps 1 to 2'

The user prompts the agent, and the agent calls the service without a token. The service answers 401 with a WWW-Authenticate header pointing to its Protected Resource Metadata. That document names the AIGW authorization server for this merchant's Resource. The agent reads the server's discovery document and registers itself with Dynamic Client Registration.

Supported

Who: User, AIGW and merchant. Diagram steps 3 to 6

The agent opens the authorization URL dedicated to the merchant's Resource, with PKCE. The user authenticates and approves the agent. AIGW then performs a token exchange with the merchant's token endpoint and stores the resulting merchant access and refresh tokens in the AIGW token vault. The merchant token is created here, before the agent receives anything.

Supported with the Playground's default Keycloak Resource. Unverified on a Resource you configure.

Tokens to the agent

Who: Agent. Diagram steps 7 to 9

AIGW redirects to the agent's callback with an authorization code. The agent exchanges the code at the AIGW token endpoint for an AIGW access token and refresh token. These tokens are AIGW's, not the merchant's.

Supported

The protected call

Who: Agent and service. Diagram steps 10 to 12

The agent calls the service again with the AIGW token. The service validates it, then asks AIGW for the merchant token by redeeming the AIGW token together with its own Proxy token. AIGW returns the merchant token from the vault, and the service calls the merchant backend with it.

Supported on a preconfigured Keycloak Resource. Release status lists what was rechecked.

Refresh

Who: AIGW. Diagram step 13

When a vaulted merchant token nears expiry, AIGW uses the merchant refresh token on the next redemption. The service does nothing differently.

If there is no refresh token, or the merchant rejects it, redemption returns 410 with reauthentication_required. Send the user through authorization again.

Why two tokens?

The agent can only reach the merchant through a service that AIGW recognizes, and only for what the user approved. If an agent token leaks, it is useless without a Proxy token from the same Project. The merchant never issues credentials to agents directly, so it needs no agent-specific changes beyond trusting AIGW.

Who owns what

Credential	Issued by	Held by
Agent client ID and secret	AIGW, at registration	Agent
AIGW access and refresh tokens	AIGW token endpoint	Agent
Proxy client ID, secret and token	AIGW, in the Console	MCP or UCP service
Merchant access and refresh tokens	Merchant token endpoint	AIGW vault, released only to the service

Standards

AIGW is built on published OAuth standards, so standard libraries work for most steps.

Standard	Used for
OAuth 2.0 and OpenID Connect	Authorization and identity
RFC 9728	Protected Resource Metadata
RFC 8414	Authorization server discovery
RFC 7591	Dynamic Client Registration
RFC 7636 (PKCE, S256)	Protecting the authorization code
RFC 7523	JWT assertions to the merchant server, private_key_jwt client authentication
RFC 8693	Token exchange with the merchant server (alternative method)
RFC 7009	Token revocation
RFC 9421	HTTP message signatures for Web Bot Auth agent proofs