openapi: 3.0.0
info:
  title: Sphereon OID4VCI API
  version: 1.0.15
  description: |
    API for OpenID for Verifiable Credential Issuance
    This API allows issuers to provide verifiable credentials to wallets following the OID4VCI specification.

    It describes the complete API, including the wallets perspective. Any wallet conforming to OID4VCI should work with these endpoints out of the box.
    From a backend you do not need to worry about these endpoints!

    The backend/webapp endpoint describe:
    - How to create a session and get a URI to include in a QR code or link
    - How to poll the issuance status
    - How to access a specific credential offer
tags:
  - name: Backend
    description: The backend/webapp endpoints that want to issue a credential
  - name: Wallet
    description: The endpoints conforming to the OID4VCI specification used by wallet implementers
  - name: Integrated Authorization Server
    description: Integrated Authorization Server endpoints (if enabled and external AS is not used)
components:
  schemas:
    Error:
      description: Standard error response format
      type: object
      properties:
        error:
          type: string
          description: Error code
          example: invalid_request
        error_description:
          type: string
          description: Human readable error description
          example: The credential offer xyz was not found
    CredentialResponse:
      description: Response containing the issued credential
      type: object
      properties:
        credentials:
          type: array
          description: Array of issued credentials. MUST NOT be present if transaction_id is present.
          items:
            type: object
            properties:
              credential:
                oneOf:
                  - type: string
                  - type: object
                description: The issued credential
          example:
            - credential: "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9..."
        transaction_id:
          type: string
          description: Identifier for deferred issuance. MUST NOT be present if credentials is present.
          example: txn-12345
        notification_id:
          type: string
          description: Identifier for notification requests
          example: notif-67890
    IssueStatusResponse:
      type: object
      description: Status of a credential issuance request
      required:
        - createdAt
        - lastUpdatedAt
        - status
      properties:
        createdAt:
          type: number
          description: Unix timestamp of when the request was created
          example: 1706533345000
        lastUpdatedAt:
          type: number
          description: Unix timestamp of the last status update
          example: 1706533346000
        status:
          $ref: '#/components/schemas/IssueStatus'
        error:
          type: string
        clientId:
          type: string
          description: Client identifier
          example: 'https://wallet.example.com'
    AuthorizationChallengeRequest:
      type: object
      description: Request to initiate authorization challenge
      properties:
        client_id:
          type: string
          description: Client identifier
          example: 'https://wallet.example.com'
        issuer_state:
          type: string
          description: Opaque state from issuer
          example: a81bc81b-dead-4563-8692-3bc3c7f12897
        auth_session:
          type: string
          description: Session identifier for associating subsequent requests
          example: d270fee1-9185-4e60-9901-d291e1338d7a
        scope:
          type: string
        code_challenge:
          type: string
        code_challenge_method:
          type: string
          enum:
            - plain
            - S256
        presentation_during_issuance_session:
          type: string
    AuthorizationChallengeResponse:
      type: object
      required:
        - authorization_code
      properties:
        authorization_code:
          type: string
    AccessTokenRequest:
      type: object
      description: Request for obtaining an access token
      required:
        - grant_type
      properties:
        client_id:
          type: string
          description: Unique identifier for the client making the request
          example: client-12345
        code:
          type: string
          description: Authorization code received from the authorization server
          example: abc123xyz
        code_verifier:
          type: string
          description: Code verifier used in the PKCE flow
          example: s256-code-verifier
        grant_type:
          type: string
          description: OAuth 2.0 grant type
          enum:
            - authorization_code
            - 'urn:ietf:params:oauth:grant-type:pre-authorized_code'
            - password
          example: authorization_code
        pre-authorized_code:
          type: string
          description: Pre-authorized code used for credential issuance
          example: pre-auth-code-xyz
        redirect_uri:
          type: string
          description: The redirect URI where the response should be sent
          example: 'https://wallet.example.com/callback'
        scope:
          type: string
          description: The scope of access requested by the client
          example: openid credential
        user_pin:
          type: string
          description: PIN required for pre-authorized flows (if applicable)
          example: '1234'
        tx_code:
          type: string
          description: Transaction code for authorization (if applicable)
          example: tx-56789
    AccessTokenResponse:
      type: object
      required:
        - access_token
        - token_type
      properties:
        access_token:
          type: string
          description: The issued access token
          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
        scope:
          type: string
          description: The granted scope(s) of the access token
          example: openid credential
        token_type:
          type: string
          description: The type of token issued (typically "Bearer")
          example: Bearer
        expires_in:
          type: number
          description: The duration in seconds for which the token is valid
          example: 3600
        authorization_pending:
          type: boolean
          description: Indicates if authorization is still pending
          example: false
        interval:
          type: number
          description: The recommended polling interval in seconds
          example: 5
        authorization_details:
          type: array
          description: Authorization details with credential identifiers (v1.0.15)
          items:
            $ref: '#/components/schemas/AuthorizationDetails'
    NotificationRequest:
      type: object
      description: Request payload for sending a notification event
      required:
        - event
      properties:
        event:
          type: string
          description: Type of the event being notified
          example: CREDENTIAL_ISSUED
        event_description:
          type: string
          description: A human-readable description of the event
          example: Credential issuance was successful.
        notification_id:
          type: string
          description: Unique identifier for the notification event
          example: notif-12345
    CredentialRequest:
      type: object
      description: |
        Request to issue a credential according to OID4VCI v1.0.15 specification.
        Exactly one of credential_identifier or credential_configuration_id MUST be present.
      properties:
        credential_identifier:
          type: string
          description: REQUIRED when authorization_details was returned from Token Response. Identifies a Credential Dataset for issuance. MUST NOT be present with credential_configuration_id.
          example: credential-dataset-123
        credential_configuration_id:
          type: string
          description: REQUIRED if credential_identifier was not returned. String identifying a key in credential_configurations_supported. MUST NOT be present with credential_identifier.
          example: UniversityDegree_JWT
        proof:
          $ref: '#/components/schemas/ProofOfPossession'
        proofs:
          $ref: '#/components/schemas/ProofOfPossessionArray'
        credential_response_encryption:
          $ref: '#/components/schemas/CredentialResponseEncryption'
        issuer_state:
          type: string
          description: OPTIONAL. Issuer state for external AS integration without nonces
    ProofOfPossession:
      type: object
      description: Proof of possession structure for credential requests
      required:
        - proof_type
        - jwt
      properties:
        proof_type:
          type: string
          description: The type of proof provided
          enum:
            - jwt
          example: jwt
        jwt:
          type: string
          description: A signed JWT containing the proof of possession
          example: eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...
    ProofOfPossessionArray:
      type: object
      description: Object containing arrays of proofs for batch credential issuance
      properties:
        jwt:
          type: array
          items:
            type: string
            description: JWT proof
          example:
            - "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9..."
            - "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9..."
    CredentialOfferPayload:
      type: object
      description: Core credential offer data
      required:
        - credential_configuration_ids
      properties:
        credential_issuer:
          type: string
          description: URL of the credential issuer
          example: 'https://agent.findynet.demo.sphereon.com/oid4vci'
        credential_configuration_ids:
          type: array
          description: Identifiers for the offered credential configurations
          items:
            type: string
          example:
            - PensionSdJwt
        grants:
          type: object
          description: Supported authorization grant types
          properties:
            'urn:ietf:params:oauth:grant-type:pre-authorized_code':
              $ref: '#/components/schemas/GrantUrnIetf'
            authorization_code:
              $ref: '#/components/schemas/GrantAuthorizationCode'
        client_id:
          type: string
          description: Optional Client identifier of the wallet
          example: 'https://wallet.example.com'
    IssueStatus:
      description: The issue status part of the issuance session
      type: string
      enum:
        - OFFER_CREATED ACCESS_TOKEN_REQUESTED
        - ACCESS_TOKEN_CREATED
        - CREDENTIAL_REQUEST_RECEIVED
        - CREDENTIAL_ISSUED
        - NOTIFICATION_CREDENTIAL_ACCEPTED
        - NOTIFICATION_CREDENTIAL_DELETED
        - NOTIFICATION_CREDENTIAL_FAILURE ERROR
    GrantAuthorizationCode:
      type: object
      properties:
        issuer_state:
          type: string
          description: 'An OAuth2 issuer_state that will be opaque to the wallet, but serves as a state correlation id between invocations as the wallet has to supply this value'
        authorization_server:
          type: string
          description: 'The authorization server to use, if the issuer metadata lists multiple authorization servers. No needed otherwise. Default to the first authorization server'
    GrantUrnIetf:
      type: object
      properties:
        pre-authorized_code:
          type: string
          description: The pre-authorized_code value that the wallet will need to supply later
          example: d270fee1-9185-4e60-9901-d291e1338d7a
        authorization_server:
          type: string
          description: 'The authorization server to use, if the issuer metadata lists multiple authorization servers. No needed otherwise. Default to the first authorization server'
        tx_code:
          $ref: '#/components/schemas/TxCode'
    TxCode:
      description: A Transaction (pin) code that can be used for a pre-authorized_code flow
      type: object
      properties:
        input_mode:
          $ref: '#/components/schemas/InputCharSet'
        length:
          type: number
          format: integer
          description: Integer specifying the length of the Transaction Code. This helps the Wallet to render the input screen and improve the user experience.
          example: 4
        description:
          type: string
          description: 'String containing guidance for the Holder of the Wallet on how to obtain the Transaction Code, e.g., describing over which communication channel it is delivered. The Wallet is RECOMMENDED to display this description next to the Transaction Code input screen to improve the user experience. The length of the string MUST NOT exceed 300 characters. The description does not support internationalization, however the Issuer MAY detect the Holder''s language by previous communication or an HTTP Accept-Language header within an HTTP GET request for a Credential Offer URI.'
          example: Please check your e-mail for a pin code
    InputCharSet:
      type: string
      enum:
        - numeric
        - text
    CredentialOfferRequest:
      description: Request to create a credential offer
      type: object
      allOf:
        - $ref: '#/components/schemas/CredentialOfferPayload'
      properties:
        baseUri:
          type: string
          description: 'Base URI for constructing offer-related links. Defaults to openid-credential-offer:// Mainly useful if you want to open the URL with a web wallet or with a native app using a different deeplink'
          example: 'openid-credential-offer://'
        scheme:
          type: string
          description: URI scheme for offer delivery
          example: openid-credential-offer
        pinLength:
          type: number
          description: Length of the user PIN if required for pre-authorization-code flow
          example: 4
        qrCodeOpts:
          type: object
          description: Options for generating a QR code representation of the offer
        credentialDataSupplierInput:
          type: object
          description: 'Additional input for the credential data supplier, this typically contains the actual credential payload (unsigned)'
          example:
            naam: Example name
            rsin: RSIN example
            straatnaam: Street example
            huisnummer: Housenumber example
            postcode: Zipcode example
            plaats: Place example
    IssuerMetadata:
      description: Credential issuer metadata as defined in the OID4VCI specification
      type: object
      required:
        - credential_configurations_supported
        - credential_issuer
        - credential_endpoint
      properties:
        credential_issuer:
          type: string
          description: URL identifying the credential issuer
          example: 'https://issuer.example.com'
        credential_configurations_supported:
          type: object
          description: Map of credential configuration IDs to their definitions
          additionalProperties:
            $ref: '#/components/schemas/CredentialConfigurationSupported'
        credential_endpoint:
          type: string
          example: 'https://issuer.example.com/credentials'
        token_endpoint:
          type: string
          description: URL of the token endpoint
        authorization_challenge_endpoint:
          type: string
          description: URL of the Authorization Challenge Endpoint
        nonce_endpoint:
          type: string
          description: NEW in v1.0.15. URL of nonce endpoint
          example: 'https://issuer.example.com/nonce'
        authorization_servers:
          type: array
          items:
            type: string
        deferred_credential_endpoint:
          type: string
        notification_endpoint:
          type: string
        batch_credential_issuance:
          $ref: '#/components/schemas/BatchCredentialIssuance'
        credential_response_encryption:
          $ref: '#/components/schemas/ResponseEncryption'
        credential_identifiers_supported:
          type: boolean
          description: Whether credential_identifiers in Token Response is supported
        display:
          type: array
          items:
            $ref: '#/components/schemas/MetadataDisplay'
          description: Display properties for different languages
    CredentialConfigurationSupported:
      type: object
      description: Defines the supported configurations for issuing credentials
      required:
        - format
      properties:
        format:
          type: string
          description: Format of the credential being issued
          example: jwt_vc_json
        scope:
          type: string
          description: 'Scope of the credential request, if applicable'
          example: openid credential
        cryptographic_binding_methods_supported:
          type: array
          items:
            type: string
          description: Supported cryptographic binding methods
        credential_signing_alg_values_supported:
          type: array
          items:
            type: string
          description: Supported credential signing algorithms
        proof_types_supported:
          type: object
          description: Types of proof supported for credential issuance
        display:
          type: array
          items:
            $ref: '#/components/schemas/CredentialsSupportedDisplay'
    BatchCredentialIssuance:
      type: object
      description: Batch issuance support information
      required:
        - batch_size
      properties:
        batch_size:
          type: integer
          description: Maximum array size for proofs parameter
          example: 5
    MetadataDisplay:
      type: object
      description: Display metadata for a credential or issuer
      properties:
        name:
          type: string
          description: Display name for the credential or issuer
          example: University Degree
        locale:
          type: string
          description: Language locale for the display information
          example: en-US
        logo:
          type: object
          properties:
            url:
              type: string
              description: URL to the logo image
            alt_text:
              type: string
              description: Alternative text for the logo
        background_color:
          type: string
          description: Background color for display components
        text_color:
          type: string
          description: Text color for display components
    CredentialsSupportedDisplay:
      type: object
      description: Display information for a credential type
      properties:
        name:
          type: string
          description: Name of the credential for display purposes
        locale:
          type: string
          description: Language locale for the credential display
        logo:
          type: object
          properties:
            url:
              type: string
              description: URL to the credential logo
            alt_text:
              type: string
              description: Alternative text for the logo
        background_color:
          type: string
          description: Background color for the credential display
        text_color:
          type: string
          description: Text color for the credential display
    AuthorizationDetails:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - openid_credential
        credential_configuration_id:
          type: string
        credential_identifiers:
          type: array
          description: Array of credential identifiers that can be issued
          items:
            type: string
        locations:
          type: array
          items:
            type: string
    AuthorizationServerMetadata:
      type: object
      description: OAuth 2.0 Authorization Server metadata with OID4VCI v1.0.15 extensions
      required:
        - issuer
        - response_types_supported
      properties:
        # Core OAuth 2.0 Authorization Server Metadata (RFC 8414)
        issuer:
          type: string
          description: Authorization server's identifier URL
          example: 'https://auth.example.com'

        authorization_endpoint:
          type: string
          description: URL of the authorization endpoint
          example: 'https://auth.example.com/authorize'

        token_endpoint:
          type: string
          description: URL of the token endpoint
          example: 'https://auth.example.com/token'

        jwks_uri:
          type: string
          description: URL of the JSON Web Key Set document
          example: 'https://auth.example.com/.well-known/jwks.json'

        registration_endpoint:
          type: string
          description: URL of the dynamic client registration endpoint
          example: 'https://auth.example.com/register'

        scopes_supported:
          type: array
          description: List of OAuth 2.0 scope values supported
          items:
            type: string
          example: ['openid', 'profile', 'email']

        response_types_supported:
          type: array
          description: List of OAuth 2.0 response_type values supported
          items:
            type: string
            enum:
              - code
              - token
              - id_token
              - 'code token'
              - 'code id_token'
              - 'token id_token'
              - 'code token id_token'
          example: ['code']

        response_modes_supported:
          type: array
          description: List of OAuth 2.0 response_mode values supported
          items:
            type: string
            enum:
              - query
              - fragment
              - form_post
          example: ['query', 'fragment']

        grant_types_supported:
          type: array
          description: List of OAuth 2.0 grant type values supported
          items:
            type: string
          example:
            - authorization_code
            - 'urn:ietf:params:oauth:grant-type:pre-authorized_code'
            - refresh_token

        token_endpoint_auth_methods_supported:
          type: array
          description: List of client authentication methods supported by token endpoint
          items:
            type: string
            enum:
              - client_secret_basic
              - client_secret_post
              - client_secret_jwt
              - private_key_jwt
              - none
          example: ['client_secret_basic', 'private_key_jwt']

        token_endpoint_auth_signing_alg_values_supported:
          type: array
          description: List of JWS signing algorithms supported for client authentication
          items:
            type: string
          example: ['RS256', 'ES256', 'PS256']

        service_documentation:
          type: string
          description: URL of human-readable service documentation
          example: 'https://auth.example.com/docs'

        ui_locales_supported:
          type: array
          description: List of UI locales supported
          items:
            type: string
          example: ['en-US', 'fr-FR', 'de-DE']

        op_policy_uri:
          type: string
          description: URL of the authorization server's policy document
          example: 'https://auth.example.com/policy'

        op_tos_uri:
          type: string
          description: URL of the authorization server's terms of service
          example: 'https://auth.example.com/tos'

        revocation_endpoint:
          type: string
          description: URL of the token revocation endpoint
          example: 'https://auth.example.com/revoke'

        revocation_endpoint_auth_methods_supported:
          type: array
          description: List of client authentication methods supported by revocation endpoint
          items:
            type: string
            enum:
              - client_secret_basic
              - client_secret_post
              - client_secret_jwt
              - private_key_jwt
              - none

        revocation_endpoint_auth_signing_alg_values_supported:
          type: array
          description: List of JWS signing algorithms for revocation endpoint authentication
          items:
            type: string
          example: ['RS256', 'ES256']

        introspection_endpoint:
          type: string
          description: URL of the token introspection endpoint
          example: 'https://auth.example.com/introspect'

        introspection_endpoint_auth_methods_supported:
          type: array
          description: List of client authentication methods supported by introspection endpoint
          items:
            type: string
            enum:
              - client_secret_basic
              - client_secret_post
              - client_secret_jwt
              - private_key_jwt
              - none

        introspection_endpoint_auth_signing_alg_values_supported:
          type: array
          description: List of JWS signing algorithms for introspection endpoint authentication
          items:
            type: string
          example: ['RS256', 'ES256']

        code_challenge_methods_supported:
          type: array
          description: List of PKCE code challenge methods supported
          items:
            type: string
            enum:
              - plain
              - S256
          example: ['S256']

        # Pushed Authorization Request (PAR) - RFC 9126
        pushed_authorization_request_endpoint:
          type: string
          description: URL of the pushed authorization request endpoint
          example: 'https://auth.example.com/par'

        require_pushed_authorization_requests:
          type: boolean
          description: Whether PAR is required for authorization requests
          default: false
          example: false

        # DPoP - RFC 9449
        dpop_signing_alg_values_supported:
          type: array
          description: List of JWS algorithms supported for DPoP proof JWTs
          items:
            type: string
          example: ['ES256', 'ES384', 'ES512', 'EdDSA']

        # OpenID Connect (if applicable)
        userinfo_endpoint:
          type: string
          description: URL of the UserInfo endpoint
          example: 'https://auth.example.com/userinfo'

        check_session_iframe:
          type: string
          description: URL of an OP iframe for session management
          example: 'https://auth.example.com/check_session'

        end_session_endpoint:
          type: string
          description: URL of the end session endpoint
          example: 'https://auth.example.com/logout'

        acr_values_supported:
          type: array
          description: List of Authentication Context Class References supported
          items:
            type: string
          example: ['urn:mace:incommon:iap:silver', 'urn:mace:incommon:iap:bronze']

        subject_types_supported:
          type: array
          description: List of Subject Identifier types supported
          items:
            type: string
            enum:
              - public
              - pairwise
          example: ['public']

        id_token_signing_alg_values_supported:
          type: array
          description: List of JWS algorithms supported for ID Token signing
          items:
            type: string
          example: ['RS256', 'ES256', 'EdDSA']

        id_token_encryption_alg_values_supported:
          type: array
          description: List of JWE algorithms supported for ID Token encryption
          items:
            type: string
          example: ['RSA-OAEP', 'ECDH-ES']

        id_token_encryption_enc_values_supported:
          type: array
          description: List of JWE encryption methods supported for ID Token
          items:
            type: string
          example: ['A256GCM', 'A128GCM']

        request_object_signing_alg_values_supported:
          type: array
          description: List of JWS algorithms supported for request objects
          items:
            type: string
          example: ['RS256', 'ES256', 'none']

        request_object_encryption_alg_values_supported:
          type: array
          description: List of JWE algorithms supported for request object encryption
          items:
            type: string
          example: ['RSA-OAEP', 'ECDH-ES']

        request_object_encryption_enc_values_supported:
          type: array
          description: List of JWE encryption methods supported for request objects
          items:
            type: string
          example: ['A256GCM', 'A128GCM']

        display_values_supported:
          type: array
          description: List of display parameter values supported
          items:
            type: string
            enum:
              - page
              - popup
              - touch
              - wap
          example: ['page', 'popup']

        claim_types_supported:
          type: array
          description: List of claim types supported
          items:
            type: string
            enum:
              - normal
              - aggregated
              - distributed
          default: ['normal']

        claims_supported:
          type: array
          description: List of claim names supported
          items:
            type: string
          example: ['sub', 'iss', 'name', 'email', 'email_verified']

        claims_parameter_supported:
          type: boolean
          description: Whether the claims parameter is supported
          default: false

        request_parameter_supported:
          type: boolean
          description: Whether the request parameter is supported
          default: false

        request_uri_parameter_supported:
          type: boolean
          description: Whether the request_uri parameter is supported
          default: true

        require_request_uri_registration:
          type: boolean
          description: Whether request_uri values must be pre-registered
          default: false

        frontchannel_logout_supported:
          type: boolean
          description: Whether front-channel logout is supported
          default: false

        frontchannel_logout_session_supported:
          type: boolean
          description: Whether front-channel logout can include session information
          default: false

        backchannel_logout_supported:
          type: boolean
          description: Whether back-channel logout is supported
          default: false

        backchannel_logout_session_supported:
          type: boolean
          description: Whether back-channel logout can include session information
          default: false

        # OID4VCI v1.0.15 Extensions
        pre-authorized_grant_anonymous_access_supported:
          type: boolean
          description: |
            OPTIONAL. Boolean indicating whether the Credential Issuer accepts a Token Request 
            with a Pre-Authorized Code but without a client_id. The default is false.
          default: false
          example: true

        authorization_challenge_endpoint:
          type: string
          description: URL of the authorization challenge endpoint (first-party apps)
          example: 'https://auth.example.com/authorization-challenge'

        # OID4VCI credential endpoints (if AS is also the issuer)
        credential_endpoint:
          type: string
          description: URL of the credential endpoint (if AS also acts as credential issuer)
          example: 'https://auth.example.com/credentials'

        deferred_credential_endpoint:
          type: string
          description: URL of the deferred credential endpoint
          example: 'https://auth.example.com/deferred-credentials'

        nonce_endpoint:
          type: string
          description: URL of the nonce endpoint (OID4VCI v1.0.15)
          example: 'https://auth.example.com/nonce'
    ResponseEncryption:
      type: object
      required:
        - alg_values_supported
        - enc_values_supported
        - encryption_required
      properties:
        alg_values_supported:
          type: array
          items:
            type: string
          example: ["ECDH-ES", "ECDH-ES+A256KW"]
        enc_values_supported:
          type: array
          items:
            type: string
          example: ["A256GCM", "A128GCM"]
        encryption_required:
          type: boolean
          description: Whether encryption is mandatory
    CredentialResponseEncryption:
      type: object
      description: Encryption parameters for credential response
      required:
        - jwk
        - alg
        - enc
      properties:
        jwk:
          type: object
          description: JWK for encryption
        alg:
          type: string
          description: JWE algorithm
          example: ECDH-ES
        enc:
          type: string
          description: Content encryption algorithm
          example: A256GCM
paths:
  /webapp/credential-offers:
    post:
      summary: Create credential offer
      description: Generate and return a new credential offer
      operationId: create-credential-offer
      tags:
        - Backend
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CredentialOfferRequest'
            examples:
              Pre Authorized Code simple:
                value:
                  credential_configuration_ids:
                    - PensionSdJwt
                  grants:
                    'urn:ietf:params:oauth:grant-type:pre-authorized_code':
                      pre-authorized_code: d270fee1-9185-4e60-9901-d291e1338d7a
                  credentialDataSupplierInput:
                    birthDate: "2000-02-11"
                    startDate: "2040-01-01"
                    endDate: "2070-05-10"
                    givenName: John
                    familyName: Doe
                    personalAdministrativeNumber: 12345678
                    typeCode: PRE
                    typeName: Pre Pension
              Pre Authorized Code simple with qr code:
                value:
                  credential_configuration_ids:
                    - PensionSdJwt
                  grants:
                    'urn:ietf:params:oauth:grant-type:pre-authorized_code':
                      pre-authorized_code: d270fee1-9185-4e60-9901-d291e1338d7b
                  qrCodeOpts: {}
                  credentialDataSupplierInput:
                    birthDate: "2000-02-11"
                    startDate: "2040-01-01"
                    endDate: "2070-05-10"
                    givenName: John
                    familyName: Doe
                    personalAdministrativeNumber: 12345678
                    typeCode: PRE
                    typeName: Pre Pension
              Pre Authorized Code with pincode:
                value:
                  credential_configuration_ids:
                    - PensionSdJwt
                  grants:
                    'urn:ietf:params:oauth:grant-type:pre-authorized_code':
                      pre-authorized_code: d270fee1-9185-4e60-9901-d291e1338d7c
                    tx_code:
                      input_mode: numeric
                      length: 4
                      description: Please check your e-mail for a pin code
                  client_id: 'https://wallet.example.com'
                  credentialDataSupplierInput:
                    birthDate: "2000-02-11"
                    startDate: "2040-01-01"
                    endDate: "2070-05-10"
                    givenName: John
                    familyName: Doe
                    personalAdministrativeNumber: 12345678
                    typeCode: PRE
                    typeName: Pre Pension
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  uri:
                    type: string
                    description: Credential offer URI
                    example: 'https://issuer.example.com/credential-offer/123'
                  userPin:
                    type: string
                    description: User PIN for access if required
                    example: '1234'
                  txCode:
                    type: object
                    description: Transaction code details for tracking
              example:
                uri: 'openid-credential-offer://?credential_offer=%7B%22credential_issuer%22%3A%22https%3A%2F%2Fagent.ssi.dev.sphereon.com%2Fdid-web%2Foid4vci%22%2C%22credential_configuration_ids%22%3A%5B%22PensionSdJwt%22%5D%2C%22grants%22%3A%7B%22urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Apre-authorized_code%22%3A%7B%22pre-authorized_code%22%3A%22d270fee1-9185-4e60-9901-d291e1338d7a%22%7D%7D%7D'
  /webapp/credential-offer-status:
    post:
      summary: Get credential issuance status
      description: Check the current status of a credential issuance request
      operationId: get-credential-offer-status
      tags:
        - Backend
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - id
              properties:
                id:
                  type: string
                  description: Identifier of the credential offer
                  example: b326c4ab-16f1-4304-83e1-4637f8fe4207
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IssueStatusResponse'
              examples:
                Offer created:
                  value:
                    createdAt: 1738694971586
                    lastUpdatedAt: 1738694971586
                    status: OFFER_CREATED
        '404':
          description: Credential offer not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  '/webapp/credential-offers/{id}':
    get:
      summary: Get credential offer
      description: Retrieve a specific credential offer by ID
      operationId: get-credential-offer
      tags:
        - Backend
      parameters:
        - name: id
          in: path
          required: true
          description: Unique identifier of the credential offer
          schema:
            type: string
          example: b326c4ab-16f1-4304-83e1-4637f8fe4207
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IssueStatusResponse'
  /.well-known/openid-credential-issuer:
    get:
      operationId: get-credential-issuer-metadata
      summary: Get credential issuer metadata
      description: 'Returns the metadata about the credential issuer''s capabilities, conforms to OID4VCI'
      tags:
        - Wallet
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IssuerMetadata'
  /.well-known/oauth-authorization-server:
    get:
      summary: 'Get authorization server metadata, if the integrated authorization server is enabled. Conforms to OAuth2'
      operationId: get-authorization-server-metadata
      tags:
        - Integrated Authorization Server
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizationServerMetadata'
  /authorization-challenge:
    post:
      summary: Authorization challenge endpoint in case a first party flow is enabled with the integrated authorization server
      operationId: authorization-challenge-endpoint
      tags:
        - Integrated Authorization Server
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthorizationChallengeRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizationChallengeResponse'
  /token:
    post:
      summary: Access token endpoint
      description: 'Issues an access token based on an authorization request, in case the integrated authorization server is enabled'
      operationId: access-token
      tags:
        - Integrated Authorization Server
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccessTokenRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessTokenResponse'
  /credentials:
    post:
      summary: Get credential endpoint
      description: Request issuance of a credential
      tags:
        - Wallet
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CredentialRequest'
      responses:
        '200':
          description: Successful response with issued credential
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CredentialResponse'
  /notification:
    post:
      summary: Notification endpoint
      operationId: notification
      tags:
        - Wallet
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NotificationRequest'
      responses:
        '204':
          description: Notification processed successfully
        '400':
          description: Invalid notification request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /nonce:
    post:
      summary: Nonce endpoint
      description: Obtain a fresh c_nonce value for proof of possession
      operationId: get-nonce
      tags:
        - Wallet
      security: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              description: Empty request body
      responses:
        '200':
          description: Successful response with fresh nonce
          content:
            application/json:
              schema:
                type: object
                required:
                  - c_nonce
                properties:
                  c_nonce:
                    type: string
                    description: Fresh nonce value
                    example: b326c4ab-16f1-4304-83e1-4637f8fe4207

servers:
  - description: Example issuer
    url: 'https://agent.findynet.demo.sphereon.com/oid4vci'
  - description: localhost
    url: 'http://localhost:5010/oid4vci'