#Wallet Integration

This guide explains how to configure a Wallet2 Service to obtain and use client attestations when requesting credentials from issuers that require attestation-based client authentication.

#Overview

The wallet integration involves two steps:

1. Obtain an attestation – The wallet requests an attestation JWT from a Client Attestation Service
2. Use the attestation – The wallet includes the attestation in credential requests to issuers

#Prerequisites

Before configuring wallet attestation:

1. Wallet or Wallet2 Service – An existing Wallet2 Service or Wallet Service in your tenant
2. Client Attestation Service – A configured Client Attestation Service in your tenant
3. Wallet Key – A key in the wallet's KMS that will be used as the instance key

#Link the Client Attester to the Wallet

First, add the Client Attestation Service as a dependency of the Wallet2 Service.

curl -X 'POST' \
  'https://{orgID}.enterprise-sandbox.waltid.dev/{version}/{target}/wallet-service-api/dependencies/add' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer {yourToken}' \
  -H 'Content-Type: application/json' \
  -d '{
  "dependency": "waltid.tenant1.client-attester1"
}'

#Obtain a Client Attestation

The wallet must obtain an attestation JWT before it can request credentials from issuers that require attestation. The attestation is stored in the wallet's resource tree and can be reused until it expires.

curl -X 'POST' \
  'https://{orgID}.enterprise-sandbox.waltid.dev/{version}/{target}/wallet-service-api/client-attestation/obtain' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {yourToken}' \
  -H 'Content-Type: application/json' \
  -d '{
  "clientAttesterServiceRef": "waltid.tenant1.client-attester1",
  "instanceKeyReference": "waltid.tenant1.kms1.wallet_key"
}'

{
  "clientAttesterServiceRef": "waltid.tenant1.client-attester1",
  "instanceKeyReference": "waltid.tenant1.kms1.wallet_key"
}

{
  "clientAttestationJwt": "eyJhbGciOiJFUzI1NiIsInR5cCI6Im9hdXRoLWNsaWVudC1hdHRlc3RhdGlvbitqd3QifQ...",
  "expiresAt": 1715270400,
  "storedAt": "waltid.tenant1.wallet1.client-attestation"
}

#Check Current Attestation

You can retrieve the wallet's current stored attestation to check its status or expiration.

curl -X 'GET' \
  'https://{orgID}.enterprise-sandbox.waltid.dev/{version}/{target}/wallet-service-api/client-attestation/current' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {yourToken}'

{
  "_id": "waltid.tenant1.wallet1.client-attestation",
  "createdAt": "2026-05-21T15:00:00Z",
  "updatedAt": "2026-05-21T15:00:00Z",
  "clientAttestationJwt": "eyJhbGciOiJFUzI1NiIsInR5cCI6Im9hdXRoLWNsaWVudC1hdHRlc3RhdGlvbitqd3QifQ...",
  "expiresAt": 1715270400,
  "attesterServiceRef": "waltid.tenant1.client-attester1",
  "parent": "waltid.tenant1.wallet1"
}

#Discover What the Issuer Expects

Before driving a receive flow, resolve the issuer’s OAuth 2.0 Authorization Server metadata (RFC 8414) for the OID4VCI authorization server referenced by the offer. In particular:

• If token_endpoint_auth_methods_supported includes attest_jwt_client_auth, the issuer is configured for attestation-based client authentication and the wallet must send the OAuth-Client-Attestation and OAuth-Client-Attestation-PoP headers on the token request (for example by setting useClientAttestation: true on wallet receive APIs, after obtaining an attestation).
• If pre_authorized_grant_anonymous_access_supported is true, the issuer allows pre-authorized code token requests without client_id when no attestation is used. If it is false and attestation is not advertised, your client may need to send client_id or use another supported method per the issuer’s configuration.

These flags follow the issuer’s clientAuthenticationConfig in the enterprise API (see Issuer integration).

#Use Attestation When Receiving Credentials

When requesting credentials from an issuer that requires attestation, set useClientAttestation: true in the receive request. The wallet will automatically:

1. Load the stored attestation
2. Build a fresh PoP JWT signed with the instance key
3. Include both in the token request headers

curl -X 'POST' \
  'https://{orgID}.enterprise-sandbox.waltid.dev/v2/{target}/wallet-service-api/credentials/receive/pre-authorized' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {yourToken}' \
  -H 'Content-Type: application/json' \
  -d '{
  "offerUrl": "openid-credential-offer://issuer.example.org/issue/?credential_offer_uri=...",
  "keyReference": "waltid.tenant1.kms1.wallet_key",
  "useClientAttestation": true
}'

{
  "offerUrl": "openid-credential-offer://issuer.example.org/issue/?credential_offer_uri=...",
  "keyReference": "waltid.tenant1.kms1.wallet_key",
  "useClientAttestation": true
}

#Attestation Lifecycle

#Expiration

Attestations have a configurable validity period (default: 24 hours). When an attestation expires:

1. The wallet will receive an error when trying to use it
2. The issuer may return a use_fresh_attestation error code
3. The wallet must obtain a new attestation before retrying

#Refresh Strategy

For production deployments, consider implementing an attestation refresh strategy:

• Proactive refresh – Obtain a new attestation before the current one expires
• Reactive refresh – Obtain a new attestation when the issuer returns use_fresh_attestation

#Error Handling

#Next Steps

• Configure Issuer Integration – Set up issuers to require attestation verification