Skip to main content

OpenID4VC - Receive and Store Credential

The Wallet Unit (WU) enables an organisation (a legal person) to act as the holder of verifiable credentials, much like a wallet holds documents in the physical world. With the Organisation Wallet Suite, your organisation can securely receive, store and manage credentials using OpenID for Verifiable Credential Issuance (OpenID4VCI) 1.0.

There are two ways to start an issuance:

  • With a credential offer from an issuer. The issuer sends you an openid-credential-offer:// URI out-of-band, for example by email or on its website.
  • From the wallet (wallet-initiated issuance). You name the issuer and the credentials that you want, and the wallet creates the offer itself and starts the Authorization Code Flow.

Receive and store a credential

Prerequisites​

  • An API key of your main organisation. See Get API Keys. Sandbox organisations do not have a holder wallet, so the holder credential operations return 400 for a sandbox organisation.
  • An operational wallet unit. Read wallet unit status must return operational or valid. Otherwise, the holder operations return 400 with Wallet Unit is not operational.

You do not need to manage any keys: the wallet signs the holder proofs with its own holder keys, so none of the requests has a key field.

Step 1: Receive the Credential​

Copy the credential offer that you received from the issuer and send it to Receive credential:

curl -X POST "https://demo-api.igrant.io/v4/config/ows/holder/credentials" \
-H "Authorization: ApiKey <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"credentialOffer": "openid-credential-offer://?credential_offer_uri=https%3A%2F%2Fissuer.example.com%2Fcredential-offer%2F6650d3c3"}'

For a wallet-initiated issuance, send the issuer and the keys of the credentials you want from its credential_configurations_supported instead of the offer. You can look up the keys with Read credential issuer metadata.

{
"credentialIssuer": "https://issuer.example.com",
"credentialConfigurationIds": ["EmployeeBadgeSdJwt"]
}

Example response (200, shortened):

{
"credential": {
"credentialId": "d29a6c1e-4b8f-4a1d-9c3e-7f5b2a0d8e11",
"credentialStatus": "credential_acked",
"credentialFormat": "dc+sd-jwt",
"requiresTransactionCode": false,
"acceptanceToken": "",
"authorisationRequest": "",
"credentialSignerTrustedListCheck": { "verified": true, "result": "trusted", "role": "pid_provider", "entry": { "status": "granted", "roles": ["pid_provider"], "source": { "id": "91ab2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "name": "EU PID providers", "kind": "etsi_lote", "url": "https://example.eu/lists/pid-providers.xml" } }, "reason": null },
"issuerTrustedListCheck": null,
"issuer": { "name": "Example Issuer", "location": "Sweden", "cover": null, "logo": null, "description": "" }
}
}

Copy the credentialId for the next steps. If the offer contains more than one credential, credential is an array.

Step 2: Finish a Pending Issuance (When Needed)​

If credentialStatus is credential_pending, the flow needs one more step:

The response showsNext step
requiresTransactionCode is trueSend the transaction code that the issuer gave the user with Receive credential with user PIN: PUT /v4/config/ows/holder/credentials/{credentialId}/transaction-code with {"transactionCode": "3491"}. txCode tells you the length and character set of the code.
acceptanceToken is setThe issuance is deferred. Call Receive deferred credential (PUT /v4/config/ows/holder/credentials/{credentialId}/deferred-credential, no body) until the status changes, waiting deferredIntervalSeconds seconds between calls.
authorisationRequest is setOpen the URL in the user's browser. After the redirect, send the code, state and iss from the redirect with Exchange code and receive credential (POST /v4/config/ows/holder/authorisation-code-exchanges).

Each of these operations returns the updated credential record.

Step 3: Accept the Credential​

Once the record is credential_acked, accept the credential into the holder wallet with Accept credential. The request has no body:

curl -X PUT "https://demo-api.igrant.io/v4/config/ows/holder/credentials/d29a6c1e-4b8f-4a1d-9c3e-7f5b2a0d8e11/acceptance" \
-H "Authorization: ApiKey <YOUR_API_KEY>"

The status changes to credential_accepted, and the wallet notifies the issuer. To decline the offer instead, delete the credential.

Step 4: List the Stored Credentials​

To list the credentials stored in the wallet, use List credential:

curl "https://demo-api.igrant.io/v4/config/ows/holder/credentials?credentialStatus=credential_accepted&groupBatches=true" \
-H "Authorization: ApiKey <YOUR_API_KEY>"

The response contains credential (an array) and pagination. With groupBatches=true, the copies of a batch issuance are grouped into a single row.

To follow issuances as they happen, open the notification stream. From a browser, first get a one-time ticket with Create SSE ticket, so that your API key stays on your server.

Trust status of the issuer

When a credential is offered, the wallet checks whether the issuer can be matched against a recognised trust list, such as the EU Trust List. If it cannot, the Data Wallet shows an "Issuer not verified" warning. This is a trust indicator, not a validation failure. See The "Issuer not verified" notice and Trust in the Wallet Ecosystem.