Issue credential
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_timeordeferred, see below).credentials: the claims of each credential configuration, one entry for each.preAuthorisedandtransactionCode: the grant of the offer (see below).- Optional: the holder (
individualIdormapperId), a data agreement (dataAgreementId), a presentation before the issuance (presentationDefinitionId), or the credential offer endpoint of a wallet (credentialOfferEndpoint).
In time or deferred
mode | Use it when | The wallet |
|---|---|---|
in_time | You have the claims now. Send an entry in credentials for each configuration. | Gets the credentials at once from the Credential Endpoint. |
deferred | The 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. AddtransactionCodeto 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
- Show
offer.urito the holder as a QR code, or as a link on a mobile device. WithindividualIdormapperId, the platform also sends a push notification to the individual. WithcredentialOfferEndpoint, the issuer sends the offer to that wallet. - Follow the issuance: the issuer events
ows.issuer.issuance_history.<event>(for exampleoffer_retrieved,credential_issued) come to your webhooks. You can also read thestatuswith Read issuance history, or with List issuance history and theofferIdfilter.
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
AuthorizationstringheaderrequiredYour API key with the prefix
ApiKey:ApiKey <your-api-key>. Get an API key.Scope:
issuances:issue
Body
The issue request. mode is required. The issuer refuses a member that it does not know (HTTP 400).
credentialDefinition Id string<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>requiredWhen 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 atransaction_idand asks again at the Deferred Credential Endpoint; claims that you gave before its credential request give the credential at once.Available options:
in_time,deferredExample:
"in_time"preAuthorised booleantrue: 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 ofauthorizationRequestTypescope_basedtakes onlyfalse.Default:
falseExample:
truetransactionCode objectAsks the issuer to make a transaction code (
tx_code, OpenID4VCI 1.0 section 4.1.1) that protects the pre-authorised code. Only withpreAuthorised: true(else HTTP 400). The issuer makes one random code for the offer and gives it only inoffer.transactionCodeof 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.individualId stringThe 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
individualIdormapperId, not both.mapperId stringYour own identifier of the individual that the offer is for (the mapper identifier of the individual). The same rules as
individualId.dataAgreement Id stringIssues the credential for a data agreement of the consent service: a
data_sourcedata agreement with theOID4VCdata exchange profile. The data agreement names the credential definition, and the issuer adds the data agreement to the claims of each configuration.presentationDefinition Id string<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 withrequiresInteractiveAuthorisation: trueand without an external OpenID provider. The presentation definition must not use a DC API response mode.transactionData objectThe 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.credentialOffer Endpoint string<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.
urlScheme enum<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://hasSignature Stamp booleantrue: the issuer puts a signature stamp on the document of the credential.Default:
falsesignatureCoordinate integer[]Where the signature stamp goes on the document: 4 integers.
4 items.
Response
The credential offer and the new issuance histories. Only this answer gives the pre-authorised code and the transaction code.
offerobjectThe credential offer of the new issuance histories. Show it to the holder as one QR code or one link.
issuanceHistory object[]The new issuance histories, one for each credential configuration of the definition, in the order of the definition.
At least 1 item.
createdAt string<date-time>When the issuer made the issuance histories (RFC 3339, UTC).
Example:
"2026-11-05T10:00:00Z"