How Credential Issuance Works

The Credential Issuance service enables you to issue Verifiable Credentials (VCs) to users and allows them to claim the VC in their digital wallet, like Affinidi Vault.

The service implements the OpenID for Verifiable Credential Issuance (OID4VCI) specification. The specification leverages the existing OAuth 2.0 authorisation flow to facilitate the secure claim of a credential offer from the issuer and allow users to store them in their digital wallet (Affinidi Vault).

Credential Issuance configuration

Before you can start the integration and enable your application to issue Verifiable Credentials (VCs) to your users, you must create the Credential Issuance configuration to configure settings such as the Wallet for cryptographically signing the VC and the list of supported schemas for issuing the credential.

The schema (credential type) is a pre-defined data structure required to create a credential offer.

Credential offer

To issue Verifiable Credentials (VCs) to your users and enable them to claim them in their digital wallets, you must first create a credential offer that contains the user’s claims. The offer must also include information on how the credential can be claimed by setting the claim mode and whether the credential is revocable.

For example, on an online course website, you can issue a credential attesting that the student has completed the course.

In the diagram below, the website calls the Credential Issuance Service to create a Credential Offer containing the details about the course and the user. It returns the URI of the Credential Offer and Transaction Code that the website sends the user to claim from the Affinidi Vault.

sequenceDiagram
    actor User
    participant Website
    participant Credential Issuance Service

    User-->>Website: Completes a course and request for certificate.
    Website->>Credential Issuance Service: Create a credential offer for the user
    Note over Website, Credential Issuance Service:  Credential data includes the supported Schema, User's wallet DID, and credential details to issue
    Credential Issuance Service->>Credential Issuance Service: Validates the credential data based on Issuance Configuration
    Credential Issuance Service->>Credential Issuance Service: Signs the Credential with the configured wallet
    Credential Issuance Service->>Website: Returns the Transaction Code and Offer URI to claim the credential from the Affinidi Vault
    Website-->>User: Send the Credential Offer claim link to the user <br />with the Transaction Code

Ensure that you present or send the URL to claim the credential offer, including the transaction code if generated securely by the user.

Claim modes

When creating a Credential Offer, you must specify the Claim Mode (claimMode) for how the user retrieves and claims the credential to store it in their Affinidi Vault. If the claim mode is not specified, the TX_CODE is used by default.

In the Credential Issuance, these are the supported claim modes:

• TX_CODE generates a transaction code that must be shared securely with the user. The user must enter the generated transaction code to retrieve and claim the credential. When creating a credential offer with TX_CODE as the claim mode, the user’s Decentralised Identifier (DID) is optional.

• FIXED_HOLDER does not generate a transaction code but requires the user’s Decentralised Identifier (DID) when creating the credential offer. The Credential Issuance service will validate if the DID of the current user claiming the credential matches the DID on the credential offer.

  To get the user’s DID, implement the  Affinidi Login to authenticate and extract the user’s DID value from the ID Token provided.

Credential offer claim flow

The credential offer is only valid for claims based on the Lifetime of the Credential Offer configured in the Credential Issuance configuration. If the user fails to claim the offer by this time, your application must create a new credential offer.

When the user clicks on the URL you sent to claim the credential offer, it redirects them to their digital wallet (Affinidi Vault). Following the OID4VCI specification, it exchanges the pre-authorisation and transaction code to get the access token required to retrieve the credential details.

sequenceDiagram
    actor User
    participant Affinidi Vault
    participant Credential Issuance Service

    User->>Affinidi Vault: Enters the Transaction Code to view the Credential Offer
    Affinidi Vault->>Credential Issuance Service: Resolves Offer URI and get the Credential Offer with Access Token
    Note over Affinidi Vault, Credential Issuance Service: Affinidi Vault will exchange Trx Code and Pre-Auth Code <br /> for the Access Token to Get the Credential
    Credential Issuance Service->>Credential Issuance Service: Validate credential proof
    Credential Issuance Service->>Credential Issuance Service: Update Credential Offer as Claimed
    Credential Issuance Service->>Affinidi Vault: Return the Verifiable Credential
    Affinidi Vault->>User: Presented the Verifiable Credential
    User->>Affinidi Vault: Accepts the Verifiable Credential
    Affinidi Vault->>Affinidi Vault: Securely Stores the Verifiable Credential

After the user accepts the credential, it is securely stored in the Affinidi Vault and can be shared later by the user when requested.

The user can claim and store the credentials only once using the same claim link. The user has the option to duplicate the claimed Verifiable Credential (VC) into different profiles available on their Affinidi Vault.

What’s next