Build an agent

Call the MCP/UCP endpoint normally. If it requires authorization, it answers 401 Unauthorized with a WWW-Authenticate header. Its resource_metadata parameter is the URL of the service's Protected Resource Metadata.

POST /mcp HTTP/1.1Host: mcp.example.comContent-Type: application/jsonHTTP/1.1 401 UnauthorizedWWW-Authenticate: Bearer resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource"

Fetch the URL from resource_metadata. The document (RFC 9728) names the authorization server that protects the service. For an AIGW-protected service, that is the per-Resource AIGW authorization server.

GET https://mcp.example.com/.well-known/oauth-protected-resource

{  "resource": "https://mcp.example.com",  "authorization_servers": [    "https://api.aigw.eval.loginid.ai/<RESOURCE_ID>"  ]}

const prm = await fetch(prmUrl).then((r) => r.json());// Use the advertised base URL. Never hard-code a Resource ID.const authServer = prm.authorization_servers[0];

Append /.well-known/openid-configuration to the advertised authorization server. The discovery document lists the per-Resource authorization endpoint, the core token endpoint, the registration endpoint, the supported scopes (including the Resource's own scopes), PKCE support and the supported token endpoint authentication methods.

GET https://api.aigw.eval.loginid.ai/<RESOURCE_ID>/.well-known/openid-configuration

{  "issuer": "<core issuer>",  "authorization_endpoint": "https://api.aigw.eval.loginid.ai/<RESOURCE_ID>/oauth2/auth",  "token_endpoint": "https://core.api.aigw.eval.loginid.ai/oauth2/token",  "registration_endpoint": "https://api.aigw.eval.loginid.ai/api/register",  "jwks_uri": "<core JWKS URL>"}

Pick the minimum scopes your MCP/UCP operation needs from the supported list. Resource scopes such as search:read appear here when the Resource defines them.

Dynamic Client Registration (RFC 7591) gives your agent its own OAuth client at runtime. No one sets it up in advance, and registration is merchant-agnostic: an agent registers once and can then reach any AIGW-protected merchant, with each merchant's policy applied on first contact.

POST https://api.aigw.eval.loginid.ai/api/registerContent-Type: application/json{  "client_name": "My agent",  "redirect_uris": ["https://agent.example.com/callback"],  "grant_types": ["authorization_code", "refresh_token"],  "response_types": ["code"],  "token_endpoint_auth_method": "client_secret_post"}

{  "client_id": "<client_id>",  "client_secret": "<client_secret>",  "client_secret_expires_at": 0,  "redirect_uris": ["https://agent.example.com/callback"],  "token_endpoint_auth_method": "client_secret_post",  "verification_method": "none"}

The response also carries the domain AIGW derived from your redirect URI and a verification_method (none when the agent doesn't sign requests). client_secret_expires_at: 0 means the secret doesn't expire, so treat it like a long-lived API key.

Generate a high-entropy code_verifier, derive code_challenge = BASE64URL(SHA256(code_verifier)), and create a random state tied to this transaction. Store the verifier and state until the callback completes, then build the authorization URL on the per-Resource endpoint.

import { createHash, randomBytes } from "node:crypto";const verifier = randomBytes(32).toString("base64url");const challenge = createHash("sha256").update(verifier).digest("base64url");const state = randomBytes(16).toString("base64url");// Store verifier and state with this transaction until the callback completes.const url = new URL(discovery.authorization_endpoint);url.search = new URLSearchParams({  response_type: "code",  client_id: client.client_id,  redirect_uri: "https://agent.example.com/callback",  scope: "openid search:read", // the minimum your MCP/UCP operation needs  state,  code_challenge: challenge,  code_challenge_method: "S256",}).toString().replace(/\+/g, "%20");// Send the user's browser to url.

The browser flow is controlled by AIGW:

• The user signs in with an identity provider enabled on the Resource.
• AIGW shows the consent request with the configured scope descriptions.
• The user approves or denies.
• On approval, AIGW redirects to your registered callback with a code and your state.

Compare the returned state with the value you stored for this transaction and reject any mismatch. Then take the code.

// AIGW redirects to:// https://agent.example.com/callback?code=<AUTHORIZATION_CODE>&state=<STATE>const params = new URL(req.url, "https://agent.example.com").searchParams;if (params.get("state") !== saved.state) {  throw new Error("state mismatch: reject this callback");}const code = params.get("code");

Post the code to the core token endpoint from discovery with the same redirect URI and your original PKCE verifier. Send the client secret in the form body, matching the client_secret_post method you registered.

POST https://core.api.aigw.eval.loginid.ai/oauth2/tokenContent-Type: application/x-www-form-urlencodedgrant_type=authorization_code&code=<AUTHORIZATION_CODE>&redirect_uri=https://agent.example.com/callback&client_id=<AGENT_CLIENT_ID>&client_secret=<AGENT_CLIENT_SECRET>&code_verifier=<ORIGINAL_CODE_VERIFIER>

{  "access_token": "<AIGW access token, a JWT>",  "id_token": "<ID token>",  "refresh_token": "<refresh token>",  "scope": "openid search:read"}

The access_token is your AIGW token. It records which user approved which agent for which scopes, and its aud is the Resource indicator it is bound to. It is not the merchant access token. The id_token carries the identity claims the user consented to, such as name, email and address, so treat it as personal data. Claim details are in the Token endpoint reference.

Retry the original MCP/UCP request with the AIGW access token as a bearer token.

POST /mcp HTTP/1.1Host: mcp.example.comAuthorization: Bearer <AIGW_ACCESS_TOKEN>Content-Type: application/json

The service pairs your token with its own server credential to obtain the merchant access token. Your agent takes no part in that exchange. From your side, the flow is complete when the service accepts the token, the tool returns a normal business response, and later calls can reuse the token while it is valid and scoped for the operation.