Skip to main content

Receive credential

POST 
/v2/config/digital-wallet/openid/sdjwt/credential/receive

Starts an OID4VCI issuance into the wallet of your organisation. The wallet reads the Credential Issuer Metadata of the issuer, gets the token, and receives the credential.

Send one of two bodies:

  • A credential offer from an issuer. Give credentialOffer.
  • A wallet-initiated issuance. Give credentialIssuer and credentialConfigurationIds. The wallet makes the credential offer itself and starts the Authorization Code Flow. Open authorizationRequest of the answer in the browser of the user, then call the exchange code operation with the code of the redirect.

Read credentialStatus of the answer. credential_acked means that the wallet holds the credential. credential_pending means that the flow needs one more step: a transaction code (userPinRequired is true), an authorization code (authorizationRequest is set), or a call to the deferred credential operation (acceptanceToken is set).

The wallet uses its own holder key. The request has no key field. A sandbox organisation has no holder wallet: the wallet refuses this operation for a sandbox organisation.

Request​

Body

required

A credential offer, or the issuer and the credential configurations of a wallet-initiated issuance.

    credentialOffer string

    Credential Offer that the issuer sends to the holder. Give the full openid-credential-offer:// URI or the credential offer URI that the issuer publishes. The wallet also accepts the field name CredentialOffer with a capital C, and uses that value when you send both.

    credentialIssuer string

    Credential Issuer Identifier, or the URL of its .well-known/openid-credential-issuer metadata document, for a wallet-initiated issuance. The wallet checks that the credential_issuer of the metadata is exactly this identifier. Use it with credentialConfigurationIds and without credentialOffer.

    credentialConfigurationIds string[]

    Keys of credential_configurations_supported in the Credential Issuer Metadata, for a wallet-initiated issuance. Give at least one. Read the keys with the Read credential issuer metadata operation.

    autoPresent boolean

    Default value: false

    When true, the wallet presents this credential automatically if a later OpenID4VP Authorization Request matches it. The default is false.

Responses​

The wallet processed the credential offer.

Response Headers
    Schema
      credential object

      Credential record that the wallet made. The wallet returns a single object if the credential offer contains one credential, an array if the offer contains more than one credential, and null if it made no record.

      oneOf
      id stringrequired

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

      credentialId stringrequired

      Unique identifier of the credential record in the wallet of the holder. Every /credential/{credentialId}/... path takes this value.

      credentialExchangeId stringrequired

      Identifier of the OID4VCI exchange at the issuer, when the wallet knows it. Use it to match the record with the issuance history of an issuer of this platform.

      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: [credential_pending, credential_acked, credential_accepted, credential_archived]

      Current status of the credential in the wallet of the holder. credential_pending means the flow needs more steps: a transaction code, an authorization 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. credential_archived marks a Wallet Unit Attestation that a newer one replaced.

      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.

      issuedAt integerrequired

      Unix time (seconds) when the wallet first stored a credential on this record. 0 when the wallet holds no credential yet.

      refreshCount integerrequired

      Number of times that the wallet replaced the credential of this record with a new one, for example after a re-issuance.

      lastRefreshedAt integerrequired

      Unix time (seconds) of the last replacement of the credential. 0 when the wallet never replaced it.

      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: [version_01]

      Version of the OID4VCI protocol of the issuance: version_01 (OpenID4VCI 1.0).

      cryptographicKeyIdentifier stringrequired

      Key identifier (kid) of the holder key that the credential is bound to.

      cryptographicKeyFormat stringrequired

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

      Format of the holder key that the credential is bound to.

      trustAnchor stringrequired

      Holds the same value as cryptographicKeyFormat.

      kid stringrequired

      Holds the same value as cryptographicKeyIdentifier.

      legalPidAttestationValidity object[]required

      Result of the check of the LPID attestation of the issuer. Each entry holds validatedAt, attestation (isExpired, isRevoked, isVerified, errors) and proofOfPossession (isExpired, isVerified, errors).

      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, and the wallet refuses to delete it.

      systemManaged booleanrequired

      When true, an extension of the organisation manages this credential, and the wallet refuses to delete it.

      batchId stringrequired

      Identifier that the copies of one batch issuance share. Empty for a credential without a batch. Accept and delete act on every copy of the batch.

      presented booleanrequired

      true when the wallet has used this copy of a batch issuance in a presentation. The wallet presents each copy of a batch once. Always false for a credential without a batch.

      deferredInterval string

      Time in seconds that the issuer asks the wallet to wait before the next call to the Deferred Credential Endpoint. Present only for a deferred issuance.

      batchInstanceCount integer

      Number of copies of the batch. Present only on a row of the list operation with groupBatches=true, for a batch issuance.

      batchAvailableCount integer

      Number of copies of the batch that the wallet has not presented yet. Present only on a row of the list operation with groupBatches=true, for a batch issuance.

      notificationId stringrequired

      notification_id from the issuer, for the OpenID4VCI Notification Endpoint.

      notificationEndpoint stringrequired

      Notification Endpoint of the issuer.

      notificationSent booleanrequired

      true after the wallet sent the notification to the issuer.

      accessTokenType string

      Type of the access token from the issuer, for example bearer or DPoP.

      dpopJwk object

      JSON Web Key (JWK) representing the holder's public key for DPoP binding.

      alg string

      Algorithm intended for use with the key.

      crv stringrequired

      Cryptographic curve.

      kid string

      Key ID used to match a specific key.

      kty stringrequired

      Key type.

      x stringrequired

      X coordinate for the EC public key (Base64URL encoded).

      y stringrequired

      Y coordinate for the EC public key (Base64URL encoded).

    Loading...
    Last updated on