---
title: "Authorization Code Flow"
description: "Full sequence diagram for issuing a credential via the OID4VCI Authorization Code Flow with an external IdP in the walt.id Enterprise Issuer2 Service."
stack: "Enterprise Stack (commercial) — version 1.1.1"
stack_version: "1.1.1"
stack_comparison: https://docs.walt.id/community-vs-enterprise.md
canonical_url: https://docs.walt.id/enterprise-stack/services/issuer2-service/protocol-flows/authorization-code-flow
generated: 2026-10-01
---
# 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 Service mapping the returned ID token claims into the credential. Set `"authMethod": "AUTHORIZED"` when [creating the offer](https://docs.walt.id/enterprise-stack/services/issuer2-service/credential-offers/create-offer.md) 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 Service** — manages the issuance session, correlates `issuer_state`, applies `idTokenClaimsMapping`, and signs the credential.
- **External IdP** — authenticates the holder and issues the ID token, configured via `authProviderConfiguration` on the issuer service.

**Error:**

This flow requires an external OAuth/OIDC provider configured via `authProviderConfiguration` when [creating the issuer service](https://docs.walt.id/enterprise-stack/services/issuer2-service/setup.md) **before** you create an `AUTHORIZED` offer.

```mermaid
sequenceDiagram
    participant App as Your Application
    participant Wallet as Wallet<br/>(Holder)
    participant Issuer as Issuer2 Service
    participant IdP as External IdP<br/>(e.g. Keycloak)

    App->>Issuer: POST /v2/{profileTarget}/issuer-service-api/credentials/offers<br/>Bearer token · {authMethod: AUTHORIZED, issuerStateMode: INCLUDE}
    activate Issuer
    Issuer->>Issuer: Create issuance session<br/>and issuer_state
    Issuer-->>App: 201 Created<br/>{credentialOffer: "openid-credential-offer://..."}
    deactivate Issuer

    App->>App: Generate QR code with<br/>credential offer URL
    App-->>Wallet: Display QR code

    Wallet->>Wallet: Scan QR code
    Wallet->>Issuer: GET issuer metadata<br/>(.well-known/openid-credential-issuer)
    Issuer-->>Wallet: Issuer metadata

    Wallet->>Issuer: GET .../openid4vci/authorize<br/>(response_type=code, issuer_state)
    activate Issuer
    Issuer->>Issuer: Resolve issuance session from issuer_state
    Issuer-->>Wallet: 302 redirect to IdP authorize URL
    deactivate Issuer

    Wallet-->>IdP: Follow redirect to authorize URL
    IdP->>IdP: User authenticates
    IdP-->>Issuer: Redirect to<br/>.../issuer-service-api/openid4vci/callback?code=...&state=...

    activate Issuer
    Issuer->>IdP: Exchange code for tokens<br/>(handled by the issuer's OAuth client)
    IdP-->>Issuer: id_token (+ access_token)
    Issuer->>Issuer: Look up session by state,<br/>apply idTokenClaimsMapping into credentialData
    Issuer-->>Wallet: 302 redirect to wallet's redirect_uri<br/>with the issuer's own authorization code
    deactivate Issuer

    Wallet->>Issuer: POST .../openid4vci/token<br/>(authorization_code)
    Issuer-->>Wallet: access_token

    Wallet->>Issuer: POST .../openid4vci/nonce
    activate Issuer
    Issuer->>Issuer: Generate fresh c_nonce
    Issuer-->>Wallet: {c_nonce}
    deactivate Issuer

    Wallet->>Wallet: Generate proof of possession<br/>(sign c_nonce with holder key)

    Wallet->>Issuer: POST .../openid4vci/credential<br/>(access_token, proof)
    activate Issuer
    Issuer->>Issuer: Sign credential using<br/>mapped claims
    Issuer-->>Wallet: 200 OK<br/>{credential}
    deactivate Issuer

    Wallet->>Wallet: Store credential
```

**Note:**

This diagram is a simplified overview focused on how the Issuer2 Service 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](https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html).

## Understanding `issuer_state`

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

`AUTHORIZED` offers omit `issuer_state` unless `issuerStateMode` is `INCLUDE`. Because per-offer overrides need this correlation, an `AUTHORIZED` offer that uses `runtimeOverrides` **must** set `issuerStateMode` to `INCLUDE` — see [Runtime Overrides](https://docs.walt.id/enterprise-stack/services/issuer2-service/credential-offers/create-offer.md#runtime-overrides).

## Related

- [Setup](https://docs.walt.id/enterprise-stack/services/issuer2-service/setup.md) — Configure `authProviderConfiguration` for the external IdP.
- [Create an Offer](https://docs.walt.id/enterprise-stack/services/issuer2-service/credential-offers/create-offer.md) — `issuerStateMode` and other offer parameters.
- [Create a Profile — ID Token Claims Mapping](https://docs.walt.id/enterprise-stack/services/issuer2-service/credential-profiles/create-profile.md#id-token-claims-mapping) — Map ID token claims into credential fields.
- [Pre-Authorized Code Flow](https://docs.walt.id/enterprise-stack/services/issuer2-service/protocol-flows/pre-authorized-flow.md) — The simpler alternative, when user login isn't needed.