Skip to main content
Issuance

Issue credential

POST/v4/config/ows/issuer/issuance-history

Starts the issuance of a credential (OpenID4VCI 1.0). The issuer makes one credential offer for a credential definition, and one issuance history for each credential configuration of the definition, in the order of the definition. The offer always has all the configurations of the definition: to issue one configuration alone, use a definition with only that configuration.

What you send

  • credentialDefinitionId: the credential definition to issue.
  • mode: when the wallet gets the credentials (in_time or deferred, see below).
  • credentials: the claims of each credential configuration, one entry for each.
  • preAuthorised and transactionCode: the grant of the offer (see below).
  • Optional: the holder (individualId or mapperId), a data agreement (dataAgreementId), a presentation before the issuance (presentationDefinitionId), or the credential offer endpoint of a wallet (credentialOfferEndpoint).

In time or deferred

modeUse it whenThe wallet
in_timeYou have the claims now. Send an entry in credentials for each configuration.Gets the credentials at once from the Credential Endpoint.
deferredThe claims come later, for example after a manual check.Gets a transaction_id and asks again at the Deferred Credential Endpoint until you give the claims with Give the claims of a deferred issuance history. Claims that you send in credentials are used at once.

Pre-authorised code or authorisation code

  • preAuthorised: true (Pre-Authorized Code Flow): you already know the holder. The offer has a pre-authorised code, and the wallet gets a token without a login. Add transactionCode to protect the code: the issuer makes a random code (for example 6 digits), and the holder types it in the wallet. Give it to the holder on another channel, for example on your web page or in an e-mail.
  • preAuthorised: false (default, Authorization Code Flow): the offer has an issuer state, and the wallet sends an authorisation request. Use it when the holder must log in first, for example at the external OpenID provider of the definition, or when the holder must present a credential (presentationDefinitionId).

What comes back

The answer (HTTP 201) has offer.uri, the credential offer URI, and one item in issuanceHistory for each configuration, with its credentialExchangeId and the status offer_sent. Only this answer gives offer.preAuthorisedCode and offer.transactionCode: you cannot read them again.

Next step

  1. Show offer.uri to the holder as a QR code, or as a link on a mobile device. With individualId or mapperId, the platform also sends a push notification to the individual. With credentialOfferEndpoint, the issuer sends the offer to that wallet.
  2. Follow the issuance: the issuer events ows.issuer.issuance_history.<event> (for example offer_retrieved, credential_issued) come to your webhooks. You can also read the status with Read issuance history, or with List issuance history and the offerId filter.

An offer that no wallet takes in time gets the status expired. The lifetime of the pre-authorised code is in the issuer configuration (600 seconds by default).

Authorizations

  • Authorizationstringheaderrequired

    Your API key with the prefix ApiKey: ApiKey <your-api-key>. Get an API key.

    Scope:issuances:issue

Body

application/json

The issue request. mode is required. The issuer refuses a member that it does not know (HTTP 400).

  • credentialDefinitionIdstring<uuid>

    The credential definition to issue, from List credential definitions. Required, except with dataAgreementId: the data agreement then names the definition, and another value gives HTTP 400.

    Example:"1f2c7a9e-5b8d-4c3e-9a1f-7d6e2b4c8a10"

  • modeenum<string>required

    When the wallet gets the credential. in_time: at once, from the Credential Endpoint; the issue call has the claims. deferred: when you give the claims. Until then the wallet gets a transaction_id and asks again at the Deferred Credential Endpoint; claims that you gave before its credential request give the credential at once.

    Available options:in_time,deferred

    Example:"in_time"

  • preAuthorisedboolean

    true: the offer has a pre-authorised code (Pre-Authorized Code Flow), and the wallet gets a token without a login. false: the offer has an issuer state, and the wallet uses the Authorization Code Flow. A definition with a configuration of authorizationRequestType scope_based takes only false.

    Default:false

    Example:true

  • transactionCodeobject

    Asks the issuer to make a transaction code (tx_code, OpenID4VCI 1.0 section 4.1.1) that protects the pre-authorised code. Only with preAuthorised: true (else HTTP 400). The issuer makes one random code for the offer and gives it only in offer.transactionCode of the answer. Give it to the holder on another channel: the wallet asks the holder for it.

  • credentialsobject[]

    The claims of the credential configurations, one entry for each configuration. in_time: required, with an entry for each configuration of the definition. A configuration of a credential type without user claims needs no entry. deferred: optional. The wallet gets the credential of a configuration with an entry at once; give the claims of the others later with Give the claims of a deferred issuance history. Each configuration can have only one entry, and each entry must name a configuration of the definition.

  • individualIdstring

    The individual that the offer is for. The platform sends a push notification about the offer to the app of the individual, so the individual must have a push notification token. Send individualId or mapperId, not both.

  • mapperIdstring

    Your own identifier of the individual that the offer is for (the mapper identifier of the individual). The same rules as individualId.

  • dataAgreementIdstring

    Issues the credential for a data agreement of the consent service: a data_source data agreement with the OID4VC data exchange profile. The data agreement names the credential definition, and the issuer adds the data agreement to the claims of each configuration.

  • presentationDefinitionIdstring<uuid>

    Dynamic credential request: the holder must present credentials of this presentation definition before the issuer gives the credential. Only with the Authorization Code Flow (preAuthorised: false), for a definition with requiresInteractiveAuthorisation: true and without an external OpenID provider. The presentation definition must not use a DC API response mode.

  • transactionDataobject

    The transaction data of the dynamic credential request, for example the payment that the holder approves with the presentation. Only with presentationDefinitionId. It must be of a transaction data type that the issuer supports.

  • credentialOfferEndpointstring<uri>

    The credential offer endpoint of a wallet, for example of an organisation wallet. After the call, the issuer sends the credential offer to this endpoint.

  • urlSchemeenum<string>

    The URL scheme of offer.uri. haip:// is for wallets of the High Assurance Interoperability Profile.

    Available options:openid-credential-offer://,haip://

    Default:openid-credential-offer://

  • hasSignatureStampboolean

    true: the issuer puts a signature stamp on the document of the credential.

    Default:false

  • signatureCoordinateinteger[]

    Where the signature stamp goes on the document: 4 integers.

    4 items.

Response

application/json

The credential offer and the new issuance histories. Only this answer gives the pre-authorised code and the transaction code.

  • offerobject

    The credential offer of the new issuance histories. Show it to the holder as one QR code or one link.

  • issuanceHistoryobject[]

    The new issuance histories, one for each credential configuration of the definition, in the order of the definition.

    At least 1 item.

  • createdAtstring<date-time>

    When the issuer made the issuance histories (RFC 3339, UTC).

    Example:"2026-11-05T10:00:00Z"