Generic OAuth authorization server
Configure your merchant authorization server to accept one of the grant patterns below, resolve the user, and issue a token for the merchant API.
Option A — RFC 7523 path (private_key_jwt in the AIGW Console)
In AIGW, this setting results in two JWTs sent to the merchant token endpoint:
- User assertion used with
grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer. - Client assertion used for JWT client authentication.
Both are ES256-signed with the AIGW Resource signing key.
User assertion claims
iss = https://api.aigw.loginid.ai/<RESOURCE_ID>
sub = <user email or AIGW pairwise subject>
aud = <merchant issuer configured in AIGW>
iat = now
exp = now + assertion lifetime
jti = unique UUID
Client assertion claims
iss = <merchant-AS client ID>
sub = <merchant-AS client ID>
aud = <merchant issuer configured in AIGW>
iat = now
exp = now + assertion lifetime
jti = unique UUID
Your AS must verify ES256 against:
https://api.aigw.loginid.ai/<RESOURCE_ID>/.well-known/jwks.json
Option B — RFC 8693 Token Exchange
AIGW can also send:
grant_type=urn:ietf:params:oauth:grant-type:token-exchange
subject_token=<AIGW signed user assertion>
subject_token_type=urn:ietf:params:oauth:token-type:jwt
requested_token_type=urn:ietf:params:oauth:token-type:access_token
resource=<Resource indicator, if configured>
scope=<requested scopes>
with JWT client authentication (client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer and a signed client_assertion).
In the Console, select token_exchange and expand Exchange request. Send resource indicator controls the resource parameter; Send requested token type controls requested_token_type. Both are on by default. Set Audience if your server requires a downstream audience, and Subject token type only if it requires an identifier other than the JWT default. The downstream audience parameter is separate from the signed assertion's aud. See Token exchange request settings.
If the merchant server requires HTTP Basic client authentication, enter the merchant client secret in the Console's Client secret field. Otherwise, AIGW uses JWT client authentication.
For an exchange that also requires an actor service account, configure actorClientId and its secret through the management API or DevCLI, the aigw command-line tool. AIGW obtains the actor access token using client credentials and includes it as actor_token with its type.
The merchant AS must accept an external AIGW-signed subject token. Do not assume a product's "standard token exchange" feature supports external subject tokens; Keycloak's standard mode does not for this pattern.
User resolution
AIGW first tries emails returned by the user's sign-in provider, then the AIGW pairwise subject. Each assertion carries one identifier as sub. AIGW tries the next identifier only when your AS returns invalid_grant with an error description containing user not found (case-insensitive). Other errors stop the request.
Scope contract
Every AIGW requested scope should exist in the merchant AS and map to the backend permission expected by the API. AIGW sends the requested/intersected scope string to the merchant token endpoint.
Response contract
For a successful merchant-token acquisition, return an OAuth access-token response. In RFC 8693 mode, AIGW requires issued_token_type and token_type, and rejects token_type: N_A because the result is not usable as an access token. Return an access token usable by the merchant API; do not treat an arbitrary JWT as a successful exchange.
Renewal contract
Provide a refresh token if the merchant session should be renewable without another user authorization. AIGW refreshes near expiry. Without a refresh token, or when the merchant rejects refresh, credential redemption returns 410 reauthentication_required; it does not silently create another user assertion from the expired authentication.