Skip to main content

Issue credential

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

Issues a Verifiable Credential to a holder using the OpenID for Verifiable Credentials Issuance (OID4VCI) protocol. Supports two issuance modes: InTime (credential issued immediately via the Credential Endpoint) and Deferred (credential issued later via the Deferred Credential Endpoint by calling the Issue deferred credential API). Supports W3C VC (JWT), IETF SD-JWT VC, and ISO 18013-5 mDoc/mDL credential formats.

Request​

Header Parameters

    X-SandboxOrgId stringrequired

    Optional. Unique identifier of the sandbox organisation to use for this request. When you send this header, the service runs the operation in the context of the named sandbox organisation, that is, against the wallet of that sandbox organisation and not against the main wallet of the organisation. Leave the header out to use the main wallet.

    The service reads this header only when you authenticate with a bearer access token. When you authenticate with an API key, the service takes the sandbox organisation from the API key and ignores this header. To run an API-key call in a sandbox organisation, bind the key to the sandbox organisation with PUT /v2/config/admin/apikey/{apiKeyId}/sandbox-org instead.

    X-SubwalletId is the deprecated name of this header. The service continues to accept it, but X-SandboxOrgId wins if you send both headers.

    The sandbox organisation must exist, must belong to your organisation and must be deployed. An unknown identifier, an identifier of a sandbox organisation that is not deployed, and an identifier that belongs to a different organisation all make the call fail with HTTP 400.

    Example: 6889e1a4c5b2f30001a3d710

Body

required

Issuance instruction. issuanceMode is the only mandatory field. Select the credential template with credentialDefinitionId or credentialDefinitionUri, and send the claims in credential or credentials. You do not set the grant type directly: the issuer uses the Pre-Authorized Code Flow when you send userPin, and the Authorization Code Flow when you do not.

    anyOf
    issuanceMode stringrequired

    Possible values: [InTime, Deferred]

    Issuance mode. InTime issues the credential immediately through the OID4VCI Credential Endpoint. Deferred issues the credential later through the Deferred Credential Endpoint.

    urlScheme string

    Default value: openid-credential-offer://

    URL scheme for the credential offer deep link. The issuer accepts any string and does not check the value. openid-credential-offer:// is the standard OID4VCI scheme and the default. haip:// is used for HAIP-compliant wallets.

    credentialDefinitionId uuid

    Identifier of a pre-configured credential definition. The issuer uses the format, type, claims structure and revocation settings of this credential definition. The value must be a valid UUID.

    credentialDefinitionUri string

    URL of an external credential definition. Use this field instead of credentialDefinitionId when the credential definition is hosted outside the platform.

    userPin string

    Possible values: <= 12 characters, Value must match regular expression ^(.{4,12})?$

    Pre-Authorized Code Flow transaction code (tx_code). When set, the wallet must include this value in the Token Request to obtain an access token. Give 4 to 12 characters. When you send this field the issuer uses the Pre-Authorized Code Flow, even if you send an empty string - an empty string selects that flow but the issuer then drops the transaction code. Leave the field out completely for the Authorisation Code Flow. You cannot combine this field with presentationDefinitionId.

    credentialOfferEndpoint string

    Credential offer endpoint URL of the wallet for issuer-initiated issuance. When you provide this URL, the issuer sends the OID4VCI Credential Offer directly to this endpoint.

    credential object

    Credential object containing the claims to be issued via the OpenID for Verifiable Credentials Issuance (OID4VCI) protocol. Structure varies by format: use type and credentialSubject for W3C VC (JWT), vct and claims for IETF SD-JWT VC, or doctype and claims for ISO 18013-5 mDoc/mDL. The issuer does not restrict the members of this object: any member that this schema does not list passes through, is stored in the credential, and is returned in the credential payload.

    type string[]

    Array of W3C Verifiable Credential type strings (e.g. ['LegalPersonIdentificationData']). Required for W3C VC (JWT) format (jwt_vc_json).

    credentialSubject object

    Key-value pairs representing the credential claims for W3C VC (JWT) format (jwt_vc_json).

    property name* any

    Key-value pairs representing the credential claims for W3C VC (JWT) format (jwt_vc_json).

    credentialMetadata object

    Free-form metadata that you want to keep with the credential. The issuer does not read or process this object: it stores the object inside the credential and returns it unchanged in the credential payload.

    property name* any

    Free-form metadata that you want to keep with the credential. The issuer does not read or process this object: it stores the object inside the credential and returns it unchanged in the credential payload.

    vct string

    Verifiable Credential Type identifier for IETF SD-JWT VC format (dc+sd-jwt).

    doctype string

    Document type identifier for ISO 18013-5 mDoc/mDL format (mso_mdoc).

    claims object

    Key-value pairs representing the credential claims for IETF SD-JWT VC (dc+sd-jwt) or ISO 18013-5 mDoc/mDL (mso_mdoc) formats.

    property name* any

    Key-value pairs representing the credential claims for IETF SD-JWT VC (dc+sd-jwt) or ISO 18013-5 mDoc/mDL (mso_mdoc) formats.

    id string

    The id field from a specific entry in the credentialDefinitions array of the create credential definition response.

    property name* any

    Credential object containing the claims to be issued via the OpenID for Verifiable Credentials Issuance (OID4VCI) protocol. Structure varies by format: use type and credentialSubject for W3C VC (JWT), vct and claims for IETF SD-JWT VC, or doctype and claims for ISO 18013-5 mDoc/mDL. The issuer does not restrict the members of this object: any member that this schema does not list passes through, is stored in the credential, and is returned in the credential payload.

    credentials object[]

    Array of credentials to issue in one exchange. Use this field when the credential definition contains more than one credential definition entry. Each entry must carry the id of the credential definition entry that it fills, because the issuer matches the entries by that value.

    presentationDefinitionId string

    Identifier of a presentation definition for dynamic credential requests. When set, the issuer requires the holder to present matching credentials through OpenID4VP before issuance continues.

    transactionData object

    Transaction data to bind to the issuance, as defined in the OpenID4VP transaction data extension. The issuer applies this field only together with credentialDefinitionId.

    property name* any

    Transaction data to bind to the issuance, as defined in the OpenID4VP transaction data extension. The issuer applies this field only together with credentialDefinitionId.

    individualId string

    Optional. Non-OID4VCI extension. Identifier of a specific individual recipient. When you provide this value, the issuer sends the credential offer as a push notification to the registered device of the individual. You cannot combine this field with mapperId.

    mapperId string

    Optional. Non-OID4VCI extension. External reference that identifies the individual recipient. The issuer resolves the individual from this value and sends the credential offer as a push notification. You cannot combine this field with individualId.

    signatureStamp boolean

    When true, the issuer adds a visible signature stamp to the issued document.

    signatureCoordinate integer[]

    Possible values: >= 4, <= 4

    Position of the signature stamp on the document page. Give exactly four pixel coordinates. The issuer refuses any other number of values.

Responses​

The issuer created the credential exchange record and the credential offer. The response holds a single object when the issuer creates one exchange record, and an array when the credential definition creates more than one record. The issuer answers 200, not 201.

Response Headers
    Schema
      credentialHistory object

      Credential exchange record, or array of credential exchange records, created for this issuance.

      oneOf
      id stringrequired

      Identifier of the credential exchange record. This field holds the same value as CredentialExchangeId.

      CredentialExchangeId stringrequired

      Unique identifier for the credential exchange record, tracking the full lifecycle of a single OID4VCI credential issuance.

      credentialExchangeId stringrequired

      Camel-case alias of CredentialExchangeId. The server sets both fields to the same value. Use this field in new integrations.

      organisationId stringrequired

      Identifier of the organisation that issues the credential.

      openIdOrganisationId stringrequired

      Identifier of the OpenID wallet deployment that processes this exchange.

      dataAgreementId stringrequired

      Identifier of the data agreement that governs this issuance. The field is empty when the issuance uses a credential definition instead of a data agreement.

      dataAttributeValues object[]required

      Attribute values supplied for a data agreement based issuance. The field is null when the issuance uses a credential definition.

    • Array [
      • name stringrequired

      Name of the data attribute, as defined in the data agreement.

      value stringrequired

      Value of the data attribute for this holder.

      limitedDisclosure boolean

      When true, the issuer makes this attribute selectively disclosable.

    • ]
      • isAccessed booleanrequired

      Indicates whether the holder opened the credential offer.

      isTokenAccessed booleanrequired

      Indicates whether the holder called the OID4VCI Token Endpoint for this exchange.

      issuanceMode stringrequired

      Possible values: [``, InTime, Deferred]

      Issuance mode used for this exchange. InTime means the credential was issued immediately via the OID4VCI Credential Endpoint. Deferred means the credential is pending via the Deferred Credential Endpoint.

      isPreAuthorised booleanrequired

      When true, the issuance used the OID4VCI Pre-Authorized Code Flow. When false, the Authorization Code Flow was used.

      credentialOffer stringrequired

      The OID4VCI Credential Offer URI sent to the holder to start the issuance flow.

      credentialOfferEndpoint stringrequired

      Credential offer endpoint of the holder wallet. The issuer sends the Credential Offer to this URL for issuer-initiated issuance.

      credentialStatus stringrequired

      Possible values: [``, pending, ready]

      Processing status of the credential. pending means the credential is being prepared. ready means it is available for the holder to retrieve.

      status stringrequired

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

      Lifecycle status of the credential exchange in the OID4VCI protocol flow: offer_sent (Credential Offer sent to holder), offer_received (holder scanned or received the offer), token_issued (issuer released an access token), credential_issued (credential issued via Credential Endpoint), credential_acked (holder acknowledged receipt), credential_accepted (holder accepted credential), credential_deleted (holder deleted credential), issuance_denied (issuer denied issuance).

      issuerState stringrequired

      Value of the OID4VCI issuer_state parameter. The issuer uses it to bind the Authorization Request to this exchange.

      authorisationRequestState stringrequired

      State value of the OAuth 2.0 Authorization Request that the wallet sent.

      idTokenRequestState stringrequired

      State value of the ID Token Request that the issuer sent to the holder.

      idTokenRequest stringrequired

      ID Token Request that the issuer sent to the holder as a signed request object.

      authorisationCodeState stringrequired

      State value that the issuer returns together with the authorisation code.

      authorisationCode stringrequired

      OAuth 2.0 authorisation code issued for the Authorization Code Flow.

      preAuthorisedCode stringrequired

      Pre-authorised code issued for the OID4VCI Pre-Authorized Code Flow.

      acceptanceToken stringrequired

      Acceptance token that the holder uses to poll the OID4VCI Deferred Credential Endpoint.

      codeChallenge stringrequired

      PKCE code challenge that the wallet sent in the Authorization Request, as defined in RFC 7636.

      codeChallengeMethod stringrequired

      PKCE code challenge method, for example S256.

      redirectUri stringrequired

      Redirect URI that the wallet registered for the Authorization Code Flow.

      clientId stringrequired

      Client identifier of the holder's wallet, typically a DID or URL. Provided during the OID4VCI Token Request.

      did stringrequired

      Decentralized Identifier of the issuer that signs the credential.

      userPin stringrequired

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

      createdAt integerrequired

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

      updatedAt integerrequired

      Unix timestamp (in seconds) when this exchange record was last modified. The list operation sorts on this field.

      limitedDisclosure booleanrequired

      When true, the issuer makes the data agreement attributes selectively disclosable in the issued credential.

      credential objectrequired

      The credential payload being issued. Contains type and credentialSubject for W3C VC (JWT) format, or vct/doctype and claims for IETF SD-JWT VC / ISO 18013-5 mDoc/mDL formats.

      property name* any

      The credential payload being issued. Contains type and credentialSubject for W3C VC (JWT) format, or vct/doctype and claims for IETF SD-JWT VC / ISO 18013-5 mDoc/mDL formats.

      disclosureMapping objectrequired

      Selective disclosure mapping for IETF SD-JWT VC credentials. Each entry maps a claim path to its disclosure setting.

      property name* any

      Selective disclosure mapping for IETF SD-JWT VC credentials. Each entry maps a claim path to its disclosure setting.

      credentialLabel stringrequired

      Label of the credential definition or data agreement that this issuance uses.

      credentialDefinitionId stringrequired

      Identifier of the credential definition that this issuance uses.

      credentialDefinitionUri stringrequired

      URL of an external credential definition that this issuance uses.

      presentationDefinitionId stringrequired

      Identifier of a presentation definition required for dynamic credential requests.

      presentationExchangeId stringrequired

      Identifier of the presentation exchange session linked to a dynamic credential request.

      holder objectrequired

      Metadata about the credential holder obtained during the OID4VCI exchange. The issuer returns only the name field. The default value before the holder starts the flow is Unknown.

      name stringrequired

      Identifier of the holder, typically a DID or display name resolved from wallet client metadata.

      credentialFormat stringrequired

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

      Credential format used for this issuance. jwt_vc_json is W3C VC (JWT). dc+sd-jwt is IETF SD-JWT VC. mso_mdoc is ISO 18013-5 mDoc/mDL. Records created by earlier releases can also hold the legacy values vc+sd-jwt, vp+sd-jwt and jwt_vc.

      supportRevocation booleanrequired

      Indicates whether revocation is enabled for the issued credential.

      revocationStatus stringrequired

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

      Current revocation status: Operational (valid), Revoked (permanently invalidated), Suspended (temporarily invalidated). The field is empty when the credential definition does not support revocation.

      clientAssertion stringrequired

      OAuth 2.0 client assertion JWT provided by the holder's wallet for client authentication.

      clientAssertionType stringrequired

      Type of the client assertion token, for example urn:ietf:params:oauth:client-assertion-type:jwt-bearer.

      clientAssertionVerified booleanrequired

      Indicates whether the holder's client assertion JWT was verified.

      walletUnitAttestation stringrequired

      Wallet Unit Attestation (WUA) credential presented by the holder, certifying the wallet instance is genuine.

      walletUnitAttestationPoP stringrequired

      Proof of Possession for the Wallet Unit Attestation.

      walletUnitAttestationVerified booleanrequired

      Indicates whether the Wallet Unit Attestation was verified.

      walletUnitValidity object[]required

      Array of wallet unit validity records containing attestation and proof of possession verification status.

    • Array [
      • attestation object

      Wallet unit attestation verification status.

      isExpired boolean

      Indicates whether the attestation has expired.

      isRevoked boolean

      Indicates whether the attestation has been revoked.

      isVerified boolean

      Indicates whether the attestation was verified.

      proofOfPossession object

      Proof of possession verification status.

      isExpired boolean

      Indicates whether the proof of possession has expired.

      isVerified boolean

      Indicates whether the proof of possession was verified.

      validatedAt integer

      Unix timestamp (in seconds) when the wallet unit validity was validated.

    • ]
      • credentialToken stringrequired

      The signed credential token (JWT, SD-JWT, or mDoc) issued to the holder.

      cnf objectrequired

      Confirmation claim (cnf) containing the holder's public key JWK for key binding.

      property name* any

      Confirmation claim (cnf) containing the holder's public key JWK for key binding.

      jti stringrequired

      JWT Token Identifier (jti), unique identifier for the issued credential token.

      proof stringrequired

      Proof JWT provided by the holder in the OID4VCI Credential Request, demonstrating key possession.

      proofType stringrequired

      Type of the proof provided in the Credential Request (e.g. jwt).

      proofVerified booleanrequired

      Indicates whether the issuer verified the holder's proof of key possession.

      decodedWalletUnitAttestation objectrequired

      Decoded payload of the holder's Wallet Unit Attestation credential.

      property name* any

      Decoded payload of the holder's Wallet Unit Attestation credential.

      idToken stringrequired

      OpenID Connect ID Token shared by the holder during the issuance flow.

      idTokenDecoded objectrequired

      Decoded payload of the holder's OpenID Connect ID Token.

      property name* any

      Decoded payload of the holder's OpenID Connect ID Token.

      idTokenVerified booleanrequired

      Indicates whether the holder's OpenID Connect ID Token was verified.

      issuanceDeniedReason stringrequired

      Human-readable reason why the issuer denied the credential issuance request.

      expiredCredentialTokens string[]required

      Array of previously issued credential tokens that have expired.

      expiredCredentials object[]required

      Array of decoded expired credential payloads.

      transactionData object

      Transaction data bound to this issuance, as defined in the OpenID4VP transaction data extension. This is the only field that the issuer leaves out when it has no value.

      property name* any

      Transaction data bound to this issuance, as defined in the OpenID4VP transaction data extension. This is the only field that the issuer leaves out when it has no value.

      credentialResponseEncryption objectrequired

      Encryption parameters that the wallet requests for the OID4VCI Credential Response. The field is null when the wallet asks for a plain response.

      alg string

      JWE key management algorithm, for example ECDH-ES.

      enc string

      JWE content encryption algorithm, for example A128GCM.

      jwk object

      Public JSON Web Key that the issuer uses to encrypt the Credential Response.

      property name* any

      Public JSON Web Key that the issuer uses to encrypt the Credential Response.

      property name* any

      Encryption parameters that the wallet requests for the OID4VCI Credential Response. The field is null when the wallet asks for a plain response.

      issuerTrustServiceProvider objectrequired

      Trust service provider record of the issuer, resolved from the trust list.

      property name* any

      Trust service provider record of the issuer, resolved from the trust list.

      holderTrustServiceProvider objectrequired

      Trust service provider record of the holder, resolved from the trust list.

      property name* any

      Trust service provider record of the holder, resolved from the trust list.

      individualId stringrequired

      Identifier of the individual recipient the credential offer was sent to.

      mapperId stringrequired

      Mapper identifier linking the credential offer to an external individual record.

      credentialResponseInterval integerrequired

      Minimum polling interval (in seconds) for the OID4VCI Deferred Credential Endpoint.

      signatureStamp booleanrequired

      When true, the issuer adds a visible signature stamp to the issued document.

      signatureCoordinate integer[]required

      Possible values: >= 4, <= 4

      Position of the signature stamp on the document page, given as four pixel coordinates.

    Loading...
    Last updated on