Wallet API FAQs
This page addresses common questions about the walt.id Wallet API for the Community Stack.
General Questions
Q: What credential formats does the Wallet support?
A: The Wallet supports multiple credential formats including:
- SD-JWT VC (IETF): Selective Disclosure JSON Web Token Verifiable Credentials
- W3C Verifiable Credentials: Versions 1.1+ and 2.0 with JSON Web signatures
- ISO 18013-5 mDL: Mobile Driver's License format
- Combined credentials: The wallet can handle multiple credentials from different issuers
Q: Which OID4VCI/VP draft versions are supported?
A: The Wallet supports OID4VCI/VP Draft 11 and Draft 13, with support for DCQL (Draft 28) coming soon. The wallet can evaluate incoming credential share requests based on different languages (DIF or DCQL) and match stored credentials for successful credential presentation.
Q: What types of wallets does walt.id support?
A: walt.id offers two main wallet variations:
- Consumer Wallet (B2C): Enables organizations to launch new identity wallet apps or embed identity wallet capabilities into existing apps for consumers. Available in both Community & Enterprise Stack.
- Organizational Wallet (B2B): Enables organizations to request, store, manage and present digital credentials of their organization and employees. Available only in the Enterprise Stack.
Architecture & Deployment
Q: What are the deployment options for the Wallet API?
A: In the Community Stack, the Wallet API is deployed as a stateful service. This enables complete custodial wallet use cases, where wallet data and keys are managed securely within the service's database.
Q: How does the Community Stack Wallet differ from the Enterprise Stack?
A: The Community Stack Wallet follows a one-user-one-wallet model with built-in authentication (email/password, OIDC or others). The Enterprise Stack supports a flexible wallet model where multiple parties can access a single wallet, includes multi-tenant support, and has no built-in end-user authentication layer - authentication is handled at the application level.
Q: What is the progressive web app (PWA) option?
A: walt.id offers a white-label progressive web app that enables wallet functionality via browser or mobile applications. It's the easiest and most effective way to demonstrate and test capabilities of credential issuance and verification services, supporting different experiences including single and cross-device flows. Its powered by the Community Stack wallet API.
Key Management & Security
Q: How does key management work with the Wallet API?
A: The Wallet API supports multiple key management approaches:
- Database storage: Keys can be stored in the configured DB of the wallet API
- External KMS: Integration with AWS KMS, Azure Key Vault, Google Cloud KMS, Hashicorp Vault, OCI KMS, and others
Q: What cryptographic operations does the wallet perform?
A: The wallet automatically performs Proof of Key/DID ownership when interacting with issuers and verifiers. It handles credential presentation signatures.
Q: How are DIDs managed in the wallet?
A: In the Community Stack, DIDs can be created, stored, and hosted directly through the Wallet API with a database specific to the API.
Credential Management
Q: How does credential storage work?
A: Credentials received from issuers can be stored in the configured database of the Wallet API.
Q: How does the wallet handle credential matching for presentation requests?
A: The wallet parses credential requests from verifiers (whether in Presentation Definition format or DCQL) and attempts to find and match credentials stored in the user's wallet to fulfill the verifier's requirements. It also handles the signing of Verifiable Presentations and holder binding JWTs.
Q: Can the wallet handle multiple credentials from different issuers?
A: Yes, the wallet is designed to handle multiple credentials from different authorities and trust chains.
Authentication & User Management
Q: How does authentication work in the Community Stack Wallet?
A: The Community Stack Wallet follows a one-user-one-wallet model with two authentication options:
- Traditional login: Email and password authentication
- External OIDC: Connection to external OIDC-compliant authentication providers
- Web3 Auth: Users login using their web3 wallet
- X.509 Certificate: Auth via x.509 certificates
Integration & Exchange
Q: How do I get started with the Wallet API?
A: Start with the getting started guide which covers setup and basic wallet operations. You can also explore the SDKs for iOS/Android integration or the progressive web app for a complete white-label solution.
Q: How does credential exchange work with issuers and verifiers?
A: The wallet supports full credential exchange flows:
- With issuers: Uses the receive endpoint to handle protocol interactions and automatically performs proof of key possession
- With verifiers: Uses the present endpoint to manage interactions, parse credential requests, match stored credentials, and sign Verifiable Presentations
Standards & Protocols
Q: What protocols does the wallet support for credential exchange?
A: The wallet integrates and supports core protocol flows based on:
- OID4VCI/VP: For receiving and presenting credentials
- ISO/IEC 18013-7: For mDL/mDoc handling
- DIF Presentation Definition: For parsing credential requests
- DCQL: Another format for credential request (coming soon)
Q: How does the wallet handle different credential formats?
A: The wallet uses a unified architecture powered by core libraries (crypto, did, openid4vc, digital-credentials, dif-definitions-parser, dcql-parser) that abstract away different credential formats. This ensures credential information can be displayed clearly to end users regardless of format.
Q: What is the role of the dif-definitions-parser library?
A: This library helps interpret presentation definitions provided by verifier parties and assists in finding and matching stored credentials in the wallet to meet specified sharing requests.
Development
Q: How does the Community Stack handle session management?
A: The Community Stack Wallet API is typically deployed as a single instance using Docker. It can be paired with a web-wallet frontend implemented as a Progressive Web App (PWA) for enhanced user experience.
Q: Can I build custom wallet applications?
A: Yes, you can build custom wallet applications using:
- REST APIs: For backend wallet functionality
- SDKs: For iOS and Android mobile applications
- Progressive Web App: For browser-based wallet solutions
- Libraries: For direct integration into existing applications