Skip to main content

Data Wallet (OpenID4VC) SDKs

The EUDI Wallet OpenID4VC SDKs for Android and iOS let you add credential issuance (OpenID4VCI 1.0) and credential presentation (OpenID4VP 1.0) to an existing Android or iOS app. Draft issuers and verifiers are still supported unless a strict policy refuses them.

Most steps return an outcome that tells you what happened, for example issued, deferred or failed, instead of an optional value. Switch on the outcome to decide the next step.

Step 01: Installation​

Add JitPack to your repositories:

settings.gradle
dependencyResolutionManagement {
repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
repositories {
google()
mavenCentral()
maven { url 'https://jitpack.io' }
}
}

Add the SDK and its required dependencies:

build.gradle
dependencies {
implementation 'com.github.decentralised-dataexchange:eudi-wallet-oid4vc-android:2026.10.5'
implementation 'com.nimbusds:nimbus-jose-jwt:9.21'
implementation 'com.squareup.retrofit2:converter-gson:2.9.0'
}

The SDK requires minSdk 28 and Java 17.

Verifiable Credential Issuance Functions​

Initialise​

Create the issuance service. On iOS, pass the key handler that holds the wallet keys: CryptoKitHandler, SecureEnclaveHandler or EDDSAKeyHandler.

MyActivity.kt
val issueService = IssueService()

Both platforms accept an offer policy. The default accepts OpenID4VCI 1.0 and draft offers. The strict policy is for conformance testing.

Resolve Credential Offer​

Pass the scanned QR code or deep link (openid-credential-offer://). The offer can be sent by value or behind a credential_offer_uri. A failure is reported on the result, never as a missing value.

MyActivity.kt
val wrappedOffer = issueService.resolveCredentialOffer(data)
val offer = wrappedOffer.credentialOffer
?: return showError(wrappedOffer.errorResponse?.errorDescription)

Issuer and Authorisation Server Metadata​

Fetch the issuer metadata, choose the authorisation server for this offer and fetch its metadata. selectAuthorizationServer applies OpenID4VCI 1.0 section 12.2.4: it uses the authorization_server named in the offer grant when there is one, and otherwise the servers listed by the issuer. Then combine the offer and both metadata documents into an issuance session, which every later request takes.

MyActivity.kt
val discovery = DiscoveryService()
val issuerConfig = discovery.getIssuerConfig(offer.credentialIssuer).issuerConfig ?: return
val authServer = discovery.selectAuthorizationServer(issuerConfig, offer)
val authConfig = discovery.getAuthConfig(authServer.identifier).authConfig ?: return

val session = IssuanceSession(offer, issuerConfig, authConfig)

getIssuerConfig accepts the credential issuer identifier with or without the /.well-known/openid-credential-issuer segment.

Create the Wallet Key and Identity​

Create Public/Private Key Pair and DID​

Create a key pair as a JSON Web Key (JWK) and a did:key identifier from it. Together they form the wallet identity used for issuance and presentation.

The wallet key is always needed: it signs the key proof in every credential request. On Android the SDK signs with the JWK in WalletIdentity. On iOS it signs with the key handler, so the JWK in WalletIdentity is optional and is not used: the key handler also signs the ID token.

The DID is used only in these cases:

WhereWhen
Key proofAs the kid, when the issuer binds credentials to a DID (for example did:key; for did:jwk the SDK makes the kid from the key instead) or the offer names a trust framework such as EBSI. Otherwise the proof carries the public JWK.
client_idIn the authorisation and token requests, when you do not send a wallet unit attestation. With one, the client_id comes from the attestation.
ID tokenWhen the authorisation server or the verifier asks for an ID token.

Create the DID anyway. WalletIdentity requires it on iOS, and it costs nothing to keep one identity for every issuer and verifier.

MyActivity.kt
val jwk = DIDService().createJWK(cryptographicAlgorithm = CryptographicAlgorithms.ES256)
val did = DIDService().createDID(jwk, CryptographicAlgorithms.ES256)

val wallet = WalletIdentity(did = did, jwk = jwk)

Wallet Attestation (optional)​

If the issuer requires a wallet unit attestation or DPoP, pass a WalletAttestation to the authorisation, token, credential, deferred and notification requests. It carries the attestation JWT, its proof of possession and the DPoP key. Leave it out when the issuer requires neither.

MyActivity.kt
val attestation = WalletAttestation(
attestationJwt = wua, // null when there is no wallet unit attestation
proofOfPossession = pop,
dpopKey = jwk as? ECKey
)

Identify the Code Flow​

A credential offer carries one of two grants:

  1. Pre-authorised code flow: the offer contains a pre-authorised code, and the token request can be sent straight away. The issuer may also require a transaction code (tx_code), usually a PIN sent to the user out of band.
  2. Authorisation code flow: the wallet sends an authorisation request first.
MyActivity.kt
val preAuthorizedCode = offer.grants?.preAuthorizationCode?.preAuthorizedCode
val isPreAuthFlow = preAuthorizedCode != null
val needsTxCode = session.requiresTransactionCode

Authorisation Request​

Skip this section for the pre-authorised code flow.

Step 1: Generate Code Verifier for Proof Key for Code Exchange (PKCE)​

MyActivity.kt
val codeVerifier = CodeVerifierService().generateCodeVerifier()

Step 2: Send Authorisation Request​

requestAuthorization builds the request, uses a pushed authorisation request (PAR) when the server requires one, and reports what the authorisation server asked for:

OutcomeWhat to do
Authorisation codeUse code in the token request.
Open in browserOpen url in the browser. The authorisation code comes back on the redirect URI.
Presentation requiredThe issuer asks for a credential first. Run the presentation flow with url. The accepted outcome carries the authorisation code.
ID token requiredAnswer with processAuthorisationRequestUsingIdToken. In in-app mode the SDK answers it for you.
FailedShow error.

Keep request.redirectUri from the response. The token request must send the same redirect URI.

MyActivity.kt
val response = issueService.requestAuthorization(
session = session,
wallet = wallet,
codeVerifier = codeVerifier,
mode = AuthorizationMode.Browser
)

val code: String? = when (response.outcome) {
AuthorizationOutcome.AUTHORIZATION_CODE -> response.code
AuthorizationOutcome.OPEN_IN_BROWSER -> {
// Open response.url, then read the code from the redirect URI
null
}
AuthorizationOutcome.PRESENTATION_REQUIRED -> {
// Present a credential using response.url (see Verifiable Presentation Functions)
null
}
AuthorizationOutcome.ID_TOKEN_REQUIRED ->
issueService.processAuthorisationRequestUsingIdToken(
did, authConfig.authorizationEndpoint, response.url, jwk
)?.let { Uri.parse(it).getQueryParameter("code") }
AuthorizationOutcome.FAILED -> return showError(response.error?.errorDescription)
}
val redirectUri = response.request?.redirectUri

To ask for a specific format or document type, pass selection = CredentialSelection(format, docType).

Token Request​

Send the token request with the grant for the flow: the authorisation code with its code verifier, or the pre-authorised code with the transaction code when the offer needs one.

MyActivity.kt
val grant = if (isPreAuthFlow) {
TokenGrant.PreAuthorized(preAuthorizedCode!!, txCode = if (needsTxCode) userPin else null)
} else {
TokenGrant.AuthorizationCode(code!!, codeVerifier, redirectUri = redirectUri)
}

val wrappedToken = issueService.requestToken(session = session, wallet = wallet, grant = grant)
val token = wrappedToken.tokenResponse
?: return showError(wrappedToken.errorResponse?.errorDescription)

Credential Request​

Request each credential in the offer. The SDK works out how to name the credential from the issuer metadata and the token response, builds the key proof, and fetches a fresh nonce from the nonce endpoint when the issuer has one. You no longer need to look up the format yourself.

Credentials can be issued in two ways:

  • In-time issuance: the credential is returned immediately.
  • Deferred issuance: the issuer returns a transaction ID and the credential is fetched later, which can take minutes to hours.
MyActivity.kt
val outcome = issueService.requestCredential(
session = session,
wallet = wallet,
token = token,
subject = CredentialSubject.of(session, token, offer.credentials?.firstOrNull()),
issuer = ClientIdentity.proofIssuer(
credentialOffer = offer,
preAuthorizedGrantAnonymousAccessSupported = authConfig.preAuthorizedGrantAnonymousAccessSupported,
clientId = did,
did = did
),
dpopNonce = wrappedToken.dpopNonce
)

when (outcome) {
is CredentialOutcome.Issued -> store(outcome.credentials)
is CredentialOutcome.Deferred -> pending = DeferredTransaction.TransactionId(outcome.transactionId)
is CredentialOutcome.Failed -> showError(outcome.error.errorDescription)
}

proofIssuer returns the iss for the key proof. It is left out when the offer is pre-authorised and the authorisation server allows anonymous access.

Deferred Credential Request​

When the credential request returns a deferred outcome, poll the deferred credential endpoint with the transaction ID. Wait interval seconds between attempts and keep polling while the outcome is deferred. Stop on failed. Draft issuers return an acceptance token instead; use LegacyAcceptanceToken for those.

MyActivity.kt
val result = issueService.requestDeferredCredential(
session = session,
token = token,
transaction = pending
)

The result is a credential outcome, handled the same way as the credential request.

Notification​

When the issued outcome carries a notificationId, tell the issuer whether the user accepted, deleted or rejected the credential.

MyActivity.kt
val result = NotificationService().notify(
session = session,
token = token,
notificationId = notificationId,
event = NotificationEvent.CREDENTIAL_ACCEPTED
)

Verifiable Presentation Functions​

The presentation functions implement OpenID4VP 1.0 with DCQL queries. Draft requests that carry a presentation_definition are still accepted unless the policy refuses them.

Initialise​

MyActivity.kt
val verificationService = VerificationService()

Resolve Authorisation Request​

Pass the scanned QR code or deep link (openid4vp://). The request can be sent by value, as a request object, or behind a request_uri fetched by GET or POST. The SDK verifies the client identifier (x509 SAN, DID, verifier attestation or redirect URI) and parses the transaction data.

On success, show the user who is asking from verifier. verified tells whether the client identifier was checked. Show the entries in transactionData too.

MyActivity.kt
val request = when (val result = verificationService.resolveAuthorizationRequest(data)) {
is PresentationRequestOutcome.Resolved -> result.request
is PresentationRequestOutcome.Failed -> return showError(result.error.errorDescription)
}

On failure, errorCode carries the OAuth error code, for example invalid_request or unsupported_response_type.

PresentationRequestPolicy.Default keeps the earlier behaviour. Pass PresentationRequestPolicy.Strict (.strict on iOS) to refuse draft requests and pre-registered clients and to require clients anchored in trustAnchors.

Match Credentials​

Match every stored credential against the DCQL query or presentation definition. Pass SD-JWT and JWT credentials in compact form and mdoc credentials as base64url IssuerSigned. The result has one entry per credential query with its candidates. If satisfiable is false, tell the user which entries (unsatisfied) cannot be met.

MyActivity.kt
val matches = verificationService.matchCredentials(request, storedCredentials)
if (!matches.satisfiable) return showError("Missing: ${matches.unsatisfied}")

// Let the user pick one candidate per entry; here the first one is taken
val selected = matches.entries.map {
SelectedCredential(entryId = it.entry.id, credential = it.candidates.first().credential)
}

SelectedCredential also takes the key the credential is bound to (key on Android, keyId on iOS). Without one, the wallet identity key signs.

Submit Presentation​

submitPresentation builds the presentations, encodes the authorisation response for the response mode and posts it to the response_uri. For strong customer authentication, pass AuthenticationMethods with the factors the user used.

OutcomeWhat to do
AcceptedOpen redirectUri when present. When the presentation was asked for during issuance, authorizationCode continues the token request.
DeliveredReturn parameters to the Digital Credentials API caller.
RefusedShow the error. The verifier accepted nothing.
MyActivity.kt
when (val outcome = verificationService.submitPresentation(request, selected, wallet)) {
is PresentationOutcome.Accepted -> outcome.redirectUri?.let { open(it) }
is PresentationOutcome.Delivered -> returnToCaller(outcome.parameters)
is PresentationOutcome.Refused -> showError(outcome.error.errorDescription)
}