How to create an OID4VCI credential offer

1. In the navigation panel on the left-hand side, expand the Credential Issuance menu.
2. Select Credential offer.
3. Select the Select button.
4. Check the checkbox next to the credential configuration you wish to include in the credential offer.
5. Select the Apply button.
6. Select the Generate button.
7. Download the generated QR code by selecting the Download button.

Make a request of the following structure to generate a new credential offer for an OID4VCI Authorization Code flow:

POST /v1/openid/offers

{
  "credentials": ["20d6bbe6-a978-447c-b5bd-f33b6dca19e2"],
  "request_parameters": {
    "login_hint": "user@example.com",
    "prompt": "login"
  }
}

• credentials : This array includes a list of identifiers for credential configurations that will be included in the credential offer. These identifiers are the id elements returned in the response when you create a Credential configuration.

  To issue multiple credential formats of the same credential in a single flow, include all the required credential configuration id elements in the request payload. For example, you could issue a CWT, JSON and/or mDocs credential using the same data in a single user journey.

• request_parameters (optional): Specifies a list of additional request parameters that are included in the credential offer and can be used by the wallet as part of the authentication workflow:

  • login_hint : Login hints are included in the authentication flow the holder is redirected to after accepting the credential offer. For example, you can include the user's e-mail so that it is already populated in the login screen.
  • prompt : Prompts are sent to the Authentication provider to control the authentication flow. For example, using login would always require the user to authenticate, even if they had already completed login on the same device.

Response

{
  "uri": "openid-credential-offer://?credential_offer=%7B%22credential_issuer%22%3A%22https%3A%2F%2Ftenant.vii.mattr.global%22%2C%22credentials%22%3A%5B%2220d6bbe6-a978-447c-b5bd-f33b6dca19e2%22%5D%2C%22request_parameters%22%3A%7B%22login_hint%22%3A%22user%40example.com%22%2C%22prompt%22%3A%22login%22%7D%7D"
}

• uri : This is the URI that should be used by the intended holder to claim the credential. For an Authorization Code flow credential offers this URI includes the parameters required to redirect the user to the configured Authentication provider to complete authentication before issuing the credential.

1. In the navigation panel on the left-hand side, expand the Credential Issuance menu.
2. Select Credential offer.
3. Use the Workflow radio button to select Pre-authorized code flow.
4. Select the Select button.
5. Check the checkbox next to the credential configuration you created in the previous step.
6. Select the Apply button.
7. Use the Claims panel to add any claims you wish to include in the issued credential.
   These claims must match the mapping defined in the Credential configuration.
8. Use the Claims to persist textbox to specify any claims you wish to persist in the MATTR VII database.
   By default no claims are persisted.
9. Use the Transaction code mode dropdown to select the desired mode for the transaction code.
10. Use the Offer valid for textbox to specify how long the offer will be valid for.
    By default, the offer is valid for 5 minutes, and the maximum allowed duration is 10 minutes.
11. Select the Generate button.
12. If a transaction code was configured, copy it from the screen.
    In production deployments you will need to provide it to the user through a different channel (e.g., email, SMS).
13. Download the displayed QR code.
    This QR code will be used by the holder to claim the credential.

Make a request of the following structure to generate a new credential offer for an OID4VCI Pre-authorized Code flow:

POST /v1/openid/offers/pre-authorized

{
  "credentials": ["707e920a-f342-443b-ae24-6946b7b5033e"],
  "userId": "b7e2c8f4-1a2b-4c3d-9e5f-8a7b6c5d4e3f",
  "transactionCodeConfiguration": {
    "inputMode": "numeric",
    "description": "Please enter the one-time code that was sent to you via email."
  },
  "claims": {
    "givenName": "John",
    "familyName": "Doe",
    "email": "john.doe@example.com",
    "userId": "e7b8c2f1-4a3d-4e6b-9c2a-1f5d8e7a9b3c"
  },
  "claimsToPersist": ["userId"],
  "expiresIn": {
    "minutes": 5,
    "seconds": 0
  }
}

• credentials : This array includes a list of identifiers for mDoc credential configurations that will be included in the credential offer. These identifiers are the id elements returned in the response when you create a Credential configuration.

  To issue multiple credential formats of the same credential in a single flow, include all the required credential configuration id elements in the request payload.

  Providing an identifier of a non-mDoc credential configuration will result in an error.

• userId : Unique system generated identifier to reference the user for this offer. This can be obtained by searching for a user. If not provided, a new user entity will be created.

• transactionCodeConfiguration : This object contains the configuration for the transaction code that will be associated with this credential offer and must be provided by the holder when claiming the credential. It includes the following properties:

  • inputMode : The input mode for the transaction code. Currently only numeric is supported.
  • description : A description of the transaction code that will be sent to the user as part of the credential offer.

• claims : This object contains the claims that will be included in the issued credential. The claims must match the mapping defined in the Credential configuration. By default, claims data is only stored for the lifetime of the offer, unless you specify them in the optional claimsToPersist array.

• claimsToPersist : This array includes a list of claims that will be persisted in the MATTR VII database. By default no claims are persisted.

• expiresIn : Specifies when the offer will expire. Once the offer expires, the user can no longer use it to claim a credential, and a new offer must be generated. The expiration period can include any combination of minutes and seconds. By default, the offer expires in 5 minutes, and the maximum allowed duration is 10 minutes.

Response

{
  "id": "b1a7c9e2-4d5f-4a6b-9e8c-2f3d4b5a6c7e", 
  "userId": "b7e2c8f4-1a2b-4c3d-9e5f-8a7b6c5d4e3f",
  "uri": "openid-credential-offer://?credential_offer=%7B%22credential_issuer%22%3A%22https%3A%2F%2Fexample.com%22%2C%22credentials%22%3A%5B%222edaf985-fcc2-4448-9c8e-a04c6c7351c2%22%5D%2C%22grants%22%3A%7B%22urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Apre-authorized_code%22%3A%7B%22pre-authorized_code%22%3A%22stukD6lg9c9tQ3jUCa32wVi1HI%2BQIVsFK%2FQPvC2CHRs%3D%22%2C%22tx_code%22%3A%7B%22length%22%3A6%2C%22input_mode%22%3A%22numeric%22%2C%22description%22%3A%22Please%20provide%20the%20one-time%20code%20that%20was%20sent%20via%20e-mail%22%7D%7D%7D%7D", 
  "expiresAt": "2025-05-01T00:01:00.000Z", 
  "transactionCode": 493536
}

• id : Unique system generated identifier to reference this offer.
• uri : This is the URI that should be used by the intended holder to claim the credential. For a Pre-authorized Code flow credential offers this URI includes the pre-authorized code which enables the wallet to retrieve the credential without requiring the user to provide any additional authentication.
• expiresAt : The date and time when the offer will expire. Once the offer expires, the user can no longer use it to claim a credential, and a new offer must be generated.
• transactionCode : This is the transaction code that must be provided by the user when claiming the credential. This code must be shared by the issuer with the holder via a separate and secure channel.