Authorization Code Flow

This flow covers your application creating a credential offer, the wallet redirecting the holder to an external IdP to authenticate, and the Issuer2 API mapping the returned ID token claims into the credential. Set "authMethod": "AUTHORIZED" when creating the offer to use it.

Components involved:

  • Your Application — creates the credential offer and displays the QR code
  • Wallet (Holder) — scans the QR code, redirects the holder to log in, completes the flow
  • Issuer2 API — manages the issuance session, correlates issuer_state, applies idTokenClaimsMapping, and signs the credential
  • External IdP — authenticates the holder and issues the ID token (registered in authentication-service.conf)

Trying this out? You don't need your own identity provider to start. If you haven't configured authentication-service.conf, Issuer2 uses a hosted walt.id test provider with ready-made login accounts (e.g. jane@walt.id / jane), so you can walk through the whole flow immediately.

For production, this flow requires your own external OAuth/OIDC provider (e.g. Keycloak, Microsoft Entra ID, Auth0) registered in authentication-service.conf before you create an AUTHORIZED offer. See Authentication Service Configuration to set one up.

Loading diagram...

This diagram is a simplified overview focused on how the Issuer2 API behaves. It omits some protocol details (e.g. metadata discovery of the Nonce Endpoint, PKCE, and the separate authorization-server metadata fetch). For the complete, normative sequence see the OpenID for Verifiable Credential Issuance 1.0 specification.

Understanding issuer_state

issuer_state is how the Issuer2 API correlates the authorization request it receives back at /authorize with the issuance session created when the offer was made. Set "issuerStateMode": "INCLUDE" when creating the offer to have it included.

By default, issuer_state is not forwarded to the external IdP — it's only used internally by the issuer. Set forwardIssuerStateToAuthorizationServer = true in authentication-service.conf only if your IdP integration specifically needs to receive it as a query parameter on the outgoing authorize request.

Related

Last updated on July 6, 2026
Pre-Authorized Code FlowProtocol Flows