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
- Android
- iOS
Add JitPack to your repositories:
dependencyResolutionManagement {
repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
repositories {
google()
mavenCentral()
maven { url 'https://jitpack.io' }
}
}
Add the SDK and its required dependencies:
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.
The SDK is available through Swift Package Manager and requires iOS 14 or later.
- In Xcode, select File > Add Package Dependencies.
- Enter the package URL
https://github.com/decentralised-dataexchange/eudi-wallet-oid4vc-iosand click Add Package. - Choose the version (for example
2026.10.9) or branch you want. - Add the
eudiWalletOidcIoslibrary to your app target.
Import the SDK where you use it:
import eudiWalletOidcIos
Verifiable Credential Issuance Functions
Initialise
Create the issuance service. On iOS, pass the key handler that holds the wallet keys: CryptoKitHandler, SecureEnclaveHandler or EDDSAKeyHandler.
- Android
- iOS
val issueService = IssueService()
let keyHandler = CryptoKitHandler()
let issueService = IssueService(keyHandler: keyHandler)
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.
- Android
- iOS
val wrappedOffer = issueService.resolveCredentialOffer(data)
val offer = wrappedOffer.credentialOffer
?: return showError(wrappedOffer.errorResponse?.errorDescription)
guard let offer = try await issueService.resolveCredentialOffer(credentialOffer: data) else { return }
if let error = offer.error {
return showError(error.message)
}
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.
- Android
- iOS
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)
let discovery = DiscoveryService.shared
guard let issuerConfig = try await discovery.getIssuerConfig(credentialIssuerWellKnownURI: offer.credentialIssuer) else { return }
let authServer = try discovery.selectAuthorizationServer(issuerConfig: issuerConfig, credentialOffer: offer)
let authConfig = try await discovery.getAuthConfig(authorisationServerWellKnownURI: authServer.identifier)
let session = IssuanceSession(credentialOffer: offer, issuerConfig: issuerConfig, authConfig: 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:
| Where | When |
|---|---|
| Key proof | As 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_id | In the authorisation and token requests, when you do not send a wallet unit attestation. With one, the client_id comes from the attestation. |
| ID token | When 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.
- Android
- iOS
val jwk = DIDService().createJWK(cryptographicAlgorithm = CryptographicAlgorithms.ES256)
val did = DIDService().createDID(jwk, CryptographicAlgorithms.ES256)
val wallet = WalletIdentity(did = did, jwk = jwk)
guard let (jwk, _) = await DidService.shared.createJWK(keyHandler: keyHandler),
let did = await DidService.shared.createDID(jwk: jwk) else { return }
let 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.
- Android
- iOS
val attestation = WalletAttestation(
attestationJwt = wua, // null when there is no wallet unit attestation
proofOfPossession = pop,
dpopKey = jwk as? ECKey
)
let attestation = WalletAttestation(
attestationJwt: wua,
proofOfPossession: pop,
dpopKeyHandler: keyHandler,
dpopKeyPublicJwk: jwk
)
Identify the Code Flow
A credential offer carries one of two grants:
- 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. - Authorisation code flow: the wallet sends an authorisation request first.
- Android
- iOS
val preAuthorizedCode = offer.grants?.preAuthorizationCode?.preAuthorizedCode
val isPreAuthFlow = preAuthorizedCode != null
val needsTxCode = session.requiresTransactionCode
let preAuthorizedCode = offer.grants?.urnIETFParamsOauthGrantTypePreAuthorizedCode?.preAuthorizedCode
let isPreAuthFlow = preAuthorizedCode != nil
let 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)
- Android
- iOS
val codeVerifier = CodeVerifierService().generateCodeVerifier()
let codeVerifier = CodeVerifierService.shared.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:
| Outcome | What to do |
|---|---|
| Authorisation code | Use code in the token request. |
| Open in browser | Open url in the browser. The authorisation code comes back on the redirect URI. |
| Presentation required | The issuer asks for a credential first. Run the presentation flow with url. The accepted outcome carries the authorisation code. |
| ID token required | Answer with processAuthorisationRequestUsingIdToken. In in-app mode the SDK answers it for you. |
| Failed | Show error. |
Keep request.redirectUri from the response. The token request must send the same redirect URI.
- Android
- iOS
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
let response = await issueService.requestAuthorization(
session: session,
wallet: wallet,
codeVerifier: codeVerifier,
mode: .browser
)
var code: String?
switch response.outcome {
case .authorizationCode:
code = response.code
case .openInBrowser:
// Open response.url, then read the code from the redirect URI
break
case .presentationRequired:
// Present a credential using response.url (see Verifiable Presentation Functions)
break
case .idTokenRequired:
// Answer with issueService.processAuthorisationRequestUsingIdToken(...)
break
case .failed:
return showError(response.error?.message)
}
let 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.
- Android
- iOS
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)
let grant: TokenGrant = isPreAuthFlow
? .preAuthorized(code: preAuthorizedCode!, txCode: needsTxCode ? userPin : nil)
: .authorizationCode(code: code!, codeVerifier: codeVerifier, redirectUri: redirectUri)
let token = await issueService.requestToken(session: session, wallet: wallet, grant: grant)
if let error = token.error {
return showError(error.message)
}
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.
- Android
- iOS
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)
}
let outcome = await issueService.requestCredential(
session: session,
wallet: wallet,
token: token,
subject: CredentialSubject.of(session: session, token: token, credential: offer.credentials?.first),
issuer: IssueService.proofIssuer(
credentialOffer: offer,
preAuthorizedGrantAnonymousAccessSupported: authConfig?.preAuthorizedGrantAnonymousAccessSupported,
clientId: did,
did: did
)
)
switch outcome {
case let .issued(credentials, notificationId, _):
store(credentials)
case let .deferred(transactionId, interval):
pending = .transactionId(transactionId)
case let .failed(error):
showError(error.message)
}
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.
- Android
- iOS
val result = issueService.requestDeferredCredential(
session = session,
token = token,
transaction = pending
)
let result = await 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.
- Android
- iOS
val result = NotificationService().notify(
session = session,
token = token,
notificationId = notificationId,
event = NotificationEvent.CREDENTIAL_ACCEPTED
)
let result = await NotificationService().notify(
session: session,
token: token,
notificationId: notificationId,
event: .credentialAccepted
)
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
- Android
- iOS
val verificationService = VerificationService()
let verificationService = VerificationService(keyhandler: keyHandler)
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.
- Android
- iOS
val request = when (val result = verificationService.resolveAuthorizationRequest(data)) {
is PresentationRequestOutcome.Resolved -> result.request
is PresentationRequestOutcome.Failed -> return showError(result.error.errorDescription)
}
let request: PresentationRequest
switch await verificationService.resolveAuthorizationRequest(data: data) {
case let .resolved(resolved):
request = resolved.request
case let .failed(error):
return showError(error.message)
}
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.
- Android
- iOS
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)
}
let matches = await verificationService.matchCredentials(request: request, credentials: storedCredentials)
guard matches.satisfiable else { return showError("Missing: \(matches.unsatisfied)") }
// Let the user pick one candidate per entry; here the first one is taken
let selected = matches.entries.compactMap { match in
match.candidates.first.map { SelectedCredential(entryId: match.entry.id, credential: $0.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.
| Outcome | What to do |
|---|---|
| Accepted | Open redirectUri when present. When the presentation was asked for during issuance, authorizationCode continues the token request. |
| Delivered | Return parameters to the Digital Credentials API caller. |
| Refused | Show the error. The verifier accepted nothing. |
- Android
- iOS
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)
}
switch await verificationService.submitPresentation(request: request, selected: selected, identity: wallet) {
case let .accepted(redirectUri, _, authorizationCode):
open(redirectUri)
case let .delivered(parameters):
returnToCaller(parameters)
case let .refused(error):
showError(error.message)
}