Application-delegated flow

Application-delegated flow allows your application to relay messages between user's wallet and Document Rails.

This may be useful if you want to use custom OID4VCI endpoints due to organizational requirements or execute custom code during particular issuance events.

We recommend using the regular flow if none of these requirements apply to your desired scenario.

Usage

To start utilizing this flow, create a credential offer with the credential_issuer value set to the URL of your application. The provided URL is going to be utilized to derive other URLs related to the OID4VCI protocol.

Your application should provide several publicly available routes.

Credential issuer metadata endpoint

This route is utilized to fetch the credential issuer metadata. Your application should either return a pre-generated value or utilize Document Rails to generate one on the fly.

Credential endpoint

This route is utilized to pass the access token from the wallet to Document Rails for initialization of the issuance process.

As a result of invoking this route, your application should respond with some kind of a transaction identifier that uniquely identifies the request.

Implementation guidance

Your application should parse the incoming request body as a JSON payload, and parse the access token value from the Authorization header.

If the body or header is empty, or any of their values are malformed, you should reject the request.

If the input is valid, you should pass it to Document Rails when invoking the recipe printing API using the oid4vci_data parameter:

Print recipe with the OID4VCI data (JavaScript)

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

await printRecipe(
    client,
    accessToken,
    organizationId,
    recipeId,
    {
        // Other params here...

        oid4vci_data: {
            // The access token parsed from the `Authorization` header.
            access_token: parsedAccessToken,

            // Identifier of the auth service that is going to be utilized for token introspection.
            auth_service_id: id,

            // Request body as a JSON value.
            request: req.body,
        },
    }
);

Deferred credential endpoint

To acquire the issuance status of the requested credential, wallets will utilize this route while providing the transaction identifier your application generated on the previous step.

Implementation guidance

Your application should handle receiving oid4vciResponse values using outbound webhooks, returning them to the user if they are available.

If the credential is still not ready, your application should return the following JSON response with the 202 HTTP status code:

{
    "transaction_id": "...",
}