Skip to content

Credential offers

To advertise the credential issuance availability to the user, OID4VCI credential offers are utilized. Credential offers are usually encoded as QR codes or deep links, presenting a familiar interfaces for your users to interact with.

Credential offers in Document Rails contain information about the credential issuance flow by including the recipe configuration and a subset of the recipe printing data.

Before creating a credential offer, make sure you configured everything else required for issuance (signing keys, credentials, etc).

Document Rails automatically determines offered credentials by scanning output credentials and determining the associated OID4VCI credential identifier.

Recipe functionality is limited

Only a subset of recipe functionality is supported in the OID4VCI issuance mode.

The following functionality is not available when issuing a credential using a credential offer:

  • Templates (ignored if configured)

  • Issuing multiple output credentials (only one of the configured output credentials is used depending on the user selection in the wallet)

Credential offers can be re-used for advertising credential issuance availability to multiple different users. Users utilizing credential offers get their own transaction identifiers for each new issuance session.

Usage

These examples assume you have created the necessary resources by this point.

import { createCredentialOffer } from "@vaultie/document-rails";

const response = await createCredentialOffer(
    client,
    accessToken,
    organizationId,
    {
        // Identifier of the recipe that is going to be utilized for credential issuance.
        recipe_id: recipeId,

        // Identifier of the auth service used for token introspection and advertising in the credential issuer manifest.
        auth_service_id: authServiceId,

        // OID4VCI grants.
        //
        // See the specification for more information.
        grants: {
            authorization_code: {},
        },

        // Optionally, you may specify the credential issuer URL if you plan to utilize the application-delegated flow.
        // Specifying this value disables the regular flow for the credential offer entirely.
        credential_issuer: "https://example.com",

        // The following parameters have the same meaning as their regular recipe printing counterpart.
        //
        // See the recipe printing documentation for more information
        issuer_configurations: {
            jwt: keyId,
        },
        status_lists: {
            [outputCredentialId]: statusListId,
        },
        validity_term: 30,
    }
);
The result of this operation is the unique identifier of the credential offer and the encoded URL that should be shared with users either as a deep link or a QR code.

This identifier can be used in other recipes to automatically embed the credential offer into generated resources as QR codes and C2PA manifest claims.

Embedding into resources

To embed existing credential offers into other recipes, set the oid4vci_credential_offer_id to the identifier of the existing credential offer.

import { createRecipe } from "@vaultie/document-rails";

const response = await createRecipe(
    client,
    accessToken,
    organizationId,
    {
        // Other recipe fields...

        oid4vci_credential_offer_id: oid4vciCredentialOfferId
    }
);

Template image variable

OID4VCI QR codes utilize the following image variable name: __impressum_oid4vci.

C2PA manifest assertion example

The C2PA OID4VCI assertion always utilizes the Document Rails-specific io.vaultie.oid4vci.offer label.

"assertions": [
    {
        "label": "io.vaultie.oid4vci.offer",
        "data": {
            "credential_offer": "openid-credential-offer://credential_offer?credential_offer=%7B%22credential_issuer%22%3A%22https%3A%2F%2Foid4vci.example.com%22%2C%22credential_configuration_ids%22%3A%5B%22com.example.pid.sd_jwt%22%5D%2C%22grants%22%3A%7B%22authorization_code%22%3A%7B%7D%7D%7D"
        }
    }
]

This label can be extracted using the verification API and third-party C2PA verifiers.