Skip to main content

OpenID4VCI - Issue Credential (In-Time)

In-time (immediate) issuance of credentials using OpenID for Verifiable Credentials Issuance (OID4VCI) involves two main stages: the creation of a credential definition and the in-time issuance of the credential.

Create Credential Definition: This involves the following sub-steps as illustrated:

  • Define: Establish the parameters and rules for the credential.
  • Prepare: Set up the necessary infrastructure and information for issuing the credential.

In-time issue: The credentials are issued after either being authorised or pre-authorised (optionally protected by a transaction code, the PIN). The holder's wallet gets the credential offer from a QR code or a link, so you do not have to configure a wallet endpoint.

Issue credential - in-Time

The image illustrates this process, showing how the credential definition is linked to the in-time issuance mechanism. The flow moves from defining and preparing the credential to an authorised issuance step, where the credential can be configured and issued to the holder's wallet. Here are the steps to follow:

Step 1: Get the API Key (Issuer Admin)​

To obtain your API key, sign in to the dashboard and go to Account > Developer APIs > Create API Key (see Get API Keys). Once you have your API key, enter it in the field below and click the Set API Key button to save it for future use.

Signing keys: The requests on this page that name a signing key sign with an x509 key of your organisation: a key with a certificate chain. After you set the API key, the page fills in such a key. To choose another key, click the key label next to a signing key field in a request, for example cryptographicKeyIdentifier. To create a key, attach a certificate or see your keys, follow the key management guide. To add your certificate to the NXD trust list, see trust list registration.

Step 2: Create Credential Definition (Issuer Admin)​

To create a credential definition, run the code block below using the Run button. Alternatively, you can manually copy the code block and use it in the body of the API request available here. From the API response, copy the credentialDefinitionId for use in Step 3. Credentials can be issued in any of the following formats:

  1. IETF SD-JWT VC
  2. ISO/IEC 18013-5:2021 mdoc/mDL
  3. W3C Verifiable Credentials Data Model - JWT

Request

Version 01
IETF SD-JWT VC

Response

Credential category: each credential configuration in credentialConfigurations has a credentialCategory, which defaults to eaa. The response shows in signingKeyCheck whether the certificate of the signing key fits the category. This is for information only and does not block the save, but a wallet or verifier may reject a credential whose certificate does not fit. For the categories, see Credential Categories and Key Usage Types.

Tip: Once a credential definition is created, the credentialDefinitionId can be reused to issue multiple credentials (Step 3). The label must be unique in the organisation: if you run Step 2 again with the same label, the API answers 400 with "Credential definition with usage purpose: ... exists for organisation". Change the label, or reuse the credentialDefinitionId of the first run.

Step 3: Issue and Receive Credential (Issuer/Holder)​

When you run Step 2 on this page, the credentialDefinitionId field and the credentialConfigurationId field of the credentials entry below are autofilled automatically (and updated whenever Step 2 is re-run). If you are executing the APIs yourself, replace <credentialDefinitionId> with the ID obtained in Step 2, and <credentialConfigurationId> with the credentialConfigurationId from the credentialConfigurations array of the Step 2 response. The issuer requests the issuance of a credential in the in_time mode: run the JSON code block below with the Run button. Choose the credential format as needed. Alternatively, you may use the API available here.

The request has one entry in credentials for each credential configuration of the credential definition, with the configuration's credentialConfigurationId and its claims. The call creates one issuance history for each configuration, all in one credential offer (see Issue a credential definition with several credential configurations). With preAuthorised: true, the offer carries a pre-authorised code, so the holder receives the credential without logging in. To protect the offer with a transaction code (PIN), add "transactionCode": {"length": 6, "inputMode": "numeric"}. The issuer generates the code and returns it only once, in offer.transactionCode, so send it to the holder through another channel.

The response contains the credential offer in offer.uri, and one item in issuanceHistory for each credential configuration, with its credentialExchangeId. Use the credentialExchangeId to read, revoke or delete the issuance history. After receiving the response, toggle the button provided to dynamically generate a QR code. The EUDI Wallet/Holder can then accept the credential offer using the Data Wallet (or any other EU Digital Identity Wallet) by either scanning the QR code or directly accessing the credential offer on their mobile device, such as via a browser.

Request

Version 01
IETF SD-JWT VC

Response

Note: The claims of each credentials entry follow the credential format of its configuration: plain claims for IETF SD-JWT VC, the mdoc namespace as the top-level key for ISO/IEC 18013-5 mdoc/mDL, and credentialSubject as the top-level key for W3C VC (JWT). The issuer sets type, vct and doctype from the credential definition. If the credential definition has no validity, the credential is valid for the default period of the issuer configuration (180 days).
Administrative expiry: A credential is never valid beyond the expiry date in its claims (expiry_date, date_of_expiry or expiryDate), and the API rejects claims whose expiry date has already passed.

Alternatively, you can manually copy the code block, update the placeholders, and use it in the body of the API request available here. From the response received, copy offer.uri and generate a QR code using a QR code generator tool, or paste the response into our tool here. The EUDI Wallet/Holder can then accept the credential offer using the Data Wallet (or any other EU Digital Identity Wallet) by either scanning the QR code or directly accessing the credential offer on their mobile device (e.g., in a browser).

Issue a credential definition with several credential configurations​

A credential definition can have more than one credential configuration, for example a PID and a Photo ID. A single issue call issues all the configurations of the definition together:

  • One call: send one entry in credentials for each credential configuration of the definition, with its credentialConfigurationId and its claims in the format of that configuration.
  • One QR code: the issuer creates a single credential offer (offer.uri) that covers all the configurations, so the holder scans only one QR code.
  • One PIN: the offer has a single pre-authorised code and transaction code (offer.transactionCode), so the holder enters the code only once.
  • One issuance history for each configuration: the response has one item in issuanceHistory for each configuration, in the order of the definition. Each issuance history has its own credentialExchangeId, status, issued credentials and webhook events, and they all share the same offerId.
  • One credential request for each configuration: the wallet gets one access token for the offer, and then sends a credential request for each configuration.

The call cannot issue only some of the configurations. To issue one configuration on its own, use a credential definition that has only that configuration.

Example request for a definition with a PID and a Photo ID configuration:

{
"credentialDefinitionId": "<credentialDefinitionId>",
"mode": "in_time",
"preAuthorised": true,
"transactionCode": { "length": 4, "inputMode": "numeric" },
"urlScheme": "openid-credential-offer://",
"credentials": [
{
"credentialConfigurationId": "<pidCredentialConfigurationId>",
"claims": {
"family_name": "Johansson",
"given_name": "Erik",
"birthdate": "1990-04-12",
"place_of_birth": { "country": "SE", "locality": "Uppsala" },
"nationalities": ["SE"],
"picture": "data:image/jpeg;base64,/9j/2wCEAP////////////////////////////////////////////////////////////////////////////////////8B///////////////////////////////////////////////////////////////////////////////////////AAAsIAAEAAQEBEQD/xADSAAABBQEBAQEBAQAAAAAAAAAAAQIDBAUGBwgJCgsQAAIBAwMCBAMFBQQEAAABfQECAwAEEQUSITFBBhNRYQcicRQygZGhCCNCscEVUtHwJDNicoIJChYXGBkaJSYnKCkqNDU2Nzg5OkNERUZHSElKU1RVVldYWVpjZGVmZ2hpanN0dXZ3eHl6g4SFhoeIiYqSk5SVlpeYmZqio6Slpqeoqaqys7S1tre4ubrCw8TFxsfIycrS09TV1tfY2drh4uPk5ebn6Onq8fLz9PX29/j5+v/aAAgBAQAAPwCSv//Z",
"issuing_authority": "Skatteverket",
"issuing_country": "SE"
}
},
{
"credentialConfigurationId": "<photoIdCredentialConfigurationId>",
"claims": {
"iso23220": { "given_name_unicode": "Erik", "family_name_unicode": "Johansson", "birth_date": "1990-04-12" },
"photoid": { "travel_document_number": "PA1234567" }
}
}
]
}

Example response:

{
"offer": {
"offerId": "2d4f1c9e-7a3b-4e58-9c1d-0b6a8e2f5d37",
"uri": "openid-credential-offer://?credential_offer_uri=https://wallet.example.com/organisation/3f6c2b1a-8d4e-4a7b-9c5d-2e1f0a9b8c7d/service/credential-offer/2d4f1c9e-7a3b-4e58-9c1d-0b6a8e2f5d37",
"offerUri": "https://wallet.example.com/organisation/3f6c2b1a-8d4e-4a7b-9c5d-2e1f0a9b8c7d/service/credential-offer/2d4f1c9e-7a3b-4e58-9c1d-0b6a8e2f5d37",
"preAuthorisedCode": "...",
"transactionCode": "3990"
},
"issuanceHistory": [
{ "credentialExchangeId": "6b0f3d2a-2c1e-4f7a-9b3d-1e5c7a9d0f42", "credentialConfigurationId": "<pidCredentialConfigurationId>", "status": "offer_sent" },
{ "credentialExchangeId": "9a1c4e7b-3d2f-4b8a-8c6e-5f0d2a7b1c93", "credentialConfigurationId": "<photoIdCredentialConfigurationId>", "status": "offer_sent" }
],
"createdAt": "2026-11-07T12:00:00Z"
}

The API rejects a request with a missing, unknown or repeated configuration with 400. In the deferred mode, credentials is optional: see Issue Credential (Deferred).

Try It Yourself (With Demo Video)​

Watch the below demo to learn issue credential API and try it out yourselves:

IETF SD-JWT VC Credential Format​

Will be published soon

ISO 18013-5 mdoc/mDL Credential Format​

ISO/IEC 18013-5 mdoc/mDL Credential Format Demo: Learn how to issue ISO/IEC 18013-5 mdoc/mDL credentials using OpenID4VCI protocol with iGrant.io Digital Wallets.

W3C VC (JWT) Credential Format​

W3C VC JWT Credential Format Demo: Learn how to issue W3C Verifiable Credentials (JWT) using OpenID4VCI protocol with iGrant.io Digital Wallets.