Skip to main content

Exchange code and receive credential

POST 
/v2/config/digital-wallet/openid/sdjwt/credential/exchange-code

Exchanges an authorization code for an access token and receives the credential in the OID4VCI Authorization Code Flow. Call this endpoint after the authorization server redirects the holder back with a code.

Request​

Body

required

Authorization code and state that the authorization server returned in the redirect.

    code stringrequired

    Possible values: non-empty

    Authorization code that the authorization server of the issuer returned in the redirect.

    credentialIds string[]

    Identifiers of the credential records to complete. Give the values that the wallet created when it processed the credential offer. If you do not give a value, the wallet uses the credential records that match the state value.

    state stringnullable

    State value that the authorization server returned in the redirect. The wallet uses this value to find the matching credential request. Send null or leave the field out when the redirect has no state.

Responses​

The wallet exchanged the code and received the credential.

Response Headers
    Schema
      credential object

      Credential that the wallet received. The wallet returns a single object if the token exchange gives one credential. The wallet returns an array if the exchange gives more than one credential.

      oneOf
      id stringrequired

      Unique identifier of the credential record. This field holds the same value as credentialId.

      credentialId stringrequired

      Unique identifier for the credential stored in the holder's wallet.

      credentialExchangeId stringrequired

      Identifier of the credential exchange that produced this credential.

      credentialToken stringrequired

      The raw JWT, SD-JWT, or mDoc token of the issued Verifiable Credential as received from the issuer's OpenID for Verifiable Credentials Issuance (OID4VCI) Credential Endpoint.

      credential objectrequired

      Decoded payload of the Verifiable Credential token. Contains the parsed claims from the W3C VC (JWT), IETF SD-JWT VC, or ISO 18013-5 mDoc/mDL credential. The field is null while the wallet waits for the credential.

      property name* any

      Decoded payload of the Verifiable Credential token. Contains the parsed claims from the W3C VC (JWT), IETF SD-JWT VC, or ISO 18013-5 mDoc/mDL credential. The field is null while the wallet waits for the credential.

      credentialStatus stringrequired

      Possible values: [``, offer_sent, offer_received, token_issued, credential_issued, credential_pending, credential_acked, credential_accepted, credential_deleted, issuance_denied]

      Current status of the credential in the holder's wallet. A stored credential normally holds one of three values. credential_pending means the credential needs more steps, for example a transaction code or a call to the OID4VCI Deferred Credential Endpoint. credential_acked means the wallet received and stored the credential. credential_accepted means the holder accepted the credential. The other values come from the issuance lifecycle and can appear while the exchange is in progress.

      acceptanceToken stringrequired

      Acceptance token (transaction_id in OID4VCI) returned for deferred issuance. The wallet uses this to poll the Deferred Credential Endpoint.

      deferredEndpoint stringrequired

      URL of the OID4VCI Deferred Credential Endpoint. Present for deferred issuance.

      credentialIssuer stringrequired

      Credential Issuer Identifier as defined in OID4VCI. Typically the issuer's base URL used to resolve the Credential Issuer Metadata.

      preAuthorisedCode stringrequired

      Pre-authorized code from the credential offer. Present for the OID4VCI Pre-Authorized Code Flow.

      userPin stringrequired

      Transaction code (tx_code) required for the OID4VCI Pre-Authorized Code Flow.

      createdAt integerrequired

      Unix timestamp (in seconds) when this credential record was created.

      updatedAt integerrequired

      Unix timestamp (in seconds) when this credential record was last modified.

      openIdOrganisationId stringrequired

      Unique identifier of the OpenID organisation (digital wallet deployment) that holds this credential.

      organisationId stringrequired

      Unique identifier of the organisation that holds this credential.

      userPinRequired booleanrequired

      When true, the holder must provide a transaction code (tx_code) to complete the OID4VCI Pre-Authorized Code Flow Token Request.

      credentialFormat stringrequired

      Possible values: [``, vc+sd-jwt, vp+sd-jwt, dc+sd-jwt, jwt_vc_json, jwt_vc, mso_mdoc]

      Format of the received credential as defined in OID4VCI. jwt_vc_json and jwt_vc are W3C VC (JWT) formats, vc+sd-jwt, vp+sd-jwt, and dc+sd-jwt are IETF SD-JWT VC formats, and mso_mdoc is the ISO 18013-5 mDoc/mDL format. The field is empty until the wallet knows the format.

      presentationId stringrequired

      Identifier linking this credential to a presentation exchange, if received as part of a dynamic issuance flow involving OpenID for Verifiable Presentation (OpenID4VP).

      issuer objectrequired

      Display information about the credential issuer, resolved from the Credential Issuer Metadata of the issuer. The wallet always returns the five fields, with empty strings when it cannot resolve the metadata.

      name stringrequired

      Display name of the issuer.

      location stringrequired

      Location of the issuer.

      cover stringrequired

      URL of the issuer's cover image.

      logo stringrequired

      URL of the issuer's logo image.

      description stringrequired

      Description of the issuer.

      credentialConfigurations objectrequired

      Credential configuration from the Credential Issuer Metadata of the issuer that applies to this credential. The keys follow the OID4VCI metadata format, for example vct, doctype, credential_definition and display.

      property name* any

      Credential configuration from the Credential Issuer Metadata of the issuer that applies to this credential. The keys follow the OID4VCI metadata format, for example vct, doctype, credential_definition and display.

      txCode objectrequired

      Transaction code (tx_code) parameters taken from the OID4VCI Credential Offer. The keys use snake case because they mirror the OID4VCI wire format. The wallet returns {"length": 0, "input_mode": "", "description": ""} when the offer has no transaction code.

      length integerrequired

      Number of characters that the transaction code has. The value is 0 when the offer has no transaction code.

      input_mode stringrequired

      Input method for the transaction code, as defined in OID4VCI. numeric accepts digits only. text accepts alphanumeric characters. The wallet stores the value that the issuer sends and does not check it. The value is empty when the offer has no transaction code.

      description stringrequired

      Instruction for the holder that explains how to get the transaction code.

      authorizationDetails object[]required

      Authorization details that the issuer returned in the OID4VCI Token Response. The field is null for the Pre-Authorized Code Flow.

    • Array [
      • type stringrequired

      Authorization detail type. The value is openid_credential for an OID4VCI credential issuance request.

      credential_configuration_id stringrequired

      Identifier of the credential configuration in the Credential Issuer Metadata of the issuer.

      credential_identifiers string[]required

      Credential identifiers that the issuer returned in the OID4VCI Token Response. The wallet sends one of these values in the Credential Request.

    • ]
      • revocationStatus stringrequired

      Possible values: [``, Operational, Revoked, Suspended]

      Current revocation status. Operational means valid, Revoked means permanently invalidated, Suspended means temporarily invalidated. The field is empty when the wallet never checked the status, or when the credential does not support revocation.

      legalPidAttestation stringrequired

      Legal Person Identification (LPID) attestation credential of the issuer, used to verify the issuer's legal identity in the EUDI Wallet ecosystem.

      legalPidAttestationPop stringrequired

      Proof of Possession (PoP) for the issuer's LPID attestation, proving the issuer controls the associated private key.

      legalPidVerified booleanrequired

      Indicates whether the issuer's LPID attestation has been successfully verified.

      autoPresent booleanrequired

      When true, the wallet automatically presents this credential when a matching OpenID4VP Authorization Request is received.

      version stringrequired

      Possible values: [``, draft_13, draft_15, draft_17, version_01]

      Version of the OID4VCI issuance protocol used for this credential. The default is draft_13.

      kid stringrequired

      Key Identifier (kid) of the cryptographic key used to sign or bind the credential.

      trustAnchor stringrequired

      Possible values: [``, did:key, x509]

      DID method or key type used as the trust anchor for verifying the issuer's identity. The default is did:key.

      expiredCredentialTokens string[]required

      Array of previously issued credential tokens that have expired.

      expiredCredentials object[]required

      Array of decoded expired credential payloads.

      requiresEncryption booleanrequired

      When true, the issuer requires encrypted OID4VCI Credential Responses for this credential.

      isVerifiedWithTrustList booleanrequired

      When true, the issuer of this credential was verified against a configured trust list.

      trustServiceProvider objectrequired

      Details of the trust service provider entry that matched the issuer during trust list verification. The field is null when the wallet found no match.

      property name* any

      Details of the trust service provider entry that matched the issuer during trust list verification. The field is null when the wallet found no match.

      oAuthFlow stringrequired

      Possible values: [``, frontchannel, backchannel]

      OAuth 2.0 flow used for credential issuance. frontchannel uses browser redirects, backchannel uses server-to-server communication. The field is empty for the Pre-Authorized Code Flow.

      authorizationRequest stringrequired

      OAuth 2.0 authorization request URL for the Authorization Code Flow.

      isWalletUnitAttestation booleanrequired

      When true, this credential is a Wallet Unit Attestation (WUA) and not a regular credential. Reissuance requests are not applicable to it.

    Loading...
    Last updated on