Frequently Asked Questions
This page addresses common questions about the walt.id Community Stack, its components, setup, and usage.
General Questions
Q: What is the walt.id Community Stack?
A: The walt.id Community Stack is a set of open-source tools designed for developers and organizations to build robust end-to-end digital identity and wallet solutions across industries and ecosystems. It provides all the necessary functionalities to launch identity solutions (issuer, verifier, and wallet) seamlessly, including multi-platform libraries, services and APIs, and white-label applications.
Q: What's the difference between the Community Stack and Enterprise Stack?
A: The Community Stack is open-source and designed to build simple end-to-end digital ID solutions in various environments using APIs, SDKs, and white-label apps. Its API services are stateless and typically deployed as single instances via Docker. The SDKs, written in Kotlin and available for Java, enable direct integration of digital ID features. The Enterprise Stack builds on top of the Community Stack and adds enterprise capabilities such as multi-tenancy support, built-in GUI management tools, lifecycle management, credential revocation mechanisms, logs, audits, pre-built integrations, and more. The Enterprise Stack is ideal for large organizations, governments, and businesses offering digital identity platforms or SaaS solutions that need to scale. Learn here.
Q: What are the main components of the Community Stack?
A: The Community Stack consists of:
- Multi-Platform Libraries: Core libraries (Crypto, SD-JWT, DIDs, OpenID4VC), credential libraries (W3C Verifiable Credentials, Mobile Driver's Licenses (ISO/IEC 18013-5 mDLs)), and ecosystem libraries
- Services and APIs: Issuer API, Verifier API, and Wallet API
- Applications: White-label web applications (Web Issuer, Web Verifier, Web Wallet)
- Command Line Interface (CLI): For trying out features directly in the terminal
- External Services & Integrations: Support for KMS/Hardware Keystores
Q: What credential formats does the Community Stack support?
A: The Community Stack 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
- Custom formats: The system is extensible to support new or proprietary formats
Q: Which protocols and standards are supported?
A: The Community Stack supports:
- OID4VCI: Draft 11 and Draft 13 for credential issuance
- OID4VP: Draft 14, 20 for credential verification
- ISO/IEC 18013-7: For mobile driver's license exchange
- Multiple DID methods: did:key, did:jwk, did:web, did:cheqd, and more
Architecture & Components
Q: How does the Community Stack architecture work?
A: The Community Stack architecture is categorized into:
- Multi-platform libraries based on Kotlin Multiplatform supporting Kotlin/Java, JavaScript, and more
- Services and APIs that enhance applications with Issuer, Verifier, and ID wallet capabilities
- Applications providing customizable white-label solutions
- External services & integrations for interoperability with third-party tools
Q: What are the three main APIs and what do they do?
A: The three main APIs are:
- Issuer API: Allows applications to issue credentials (VCs, mdocs) across ecosystems via OID4VCI
- Verifier API: Enables applications to verify credentials (VCs, mdocs) based on various verification policies via OID4VP
- Wallet API: Extends applications with identity wallet capabilities for collecting, storing, managing, and sharing identity credentials
Q: What white-label applications are available?
A: The Community Stack includes:
- Web Issuer: A web portal supporting OIDC4VC for credential issuance
- Web Verifier: A web portal supporting OIDC4VP for credential verification
- Web Wallet: A custodial web-wallet (PWA) for collecting, managing, and sharing credentials
Setup & Deployment
Q: How do I get started with the Community Stack?
A: You can get started in several ways:
- Quick Start: Use our docker compose to spin up all services locally
- Individual APIs: Set up specific APIs (Issuer, Verifier, Wallet) using Docker or open-source installation
- White-label Apps: Use the pre-built web applications for immediate testing
- SDKs: Integrate the Kotlin/Java libraries directly into your applications
Q: What are the system requirements for running the Community Stack?
A: The Community Stack requires:
- Docker: For containerized deployment
- Java/Kotlin: For SDK usage
- Node.js: For web applications (if running locally)
Q: Can I run the Community Stack without Docker?
A: Yes, you can run individual components without Docker:
- APIs: Build from source using Gradle/Maven
- Web Apps: Run locally with Node.js
- SDKs: Include as dependencies in your Kotlin/Java projects
Q: How do I access the services once they're running?
A: When running via docker-compose, you can access:
- Issuer API: Local | Deployed
- Verifier API: Local | Deployed
- Wallet API: Local | Deployed
- Web Wallet: Local | Deployed
- Web Portal: Local | Deployed
Key Management & Security
Q: How does key management work in the Community Stack?
A: The Community Stack is KMS-agnostic and supports:
- External KMS: AWS KMS, Azure Key Vault, Google Cloud KMS, Hashicorp Vault, OCI KMS
- Raw key material: For development and PoC environments
- Multiple algorithms: ed25519, secp256k1, secp256r1, and RSA
Q: What cryptographic algorithms are supported?
A: The Community Stack supports multiple asymmetric key types including ed25519, secp256k1, secp256r1, and RSA.
Q: How do I integrate with my existing KMS infrastructure?
A: The system supports multiple authentication methods:
- Cloud environments: Use automatically assigned roles (like AWS IAM roles) for keyless authentication
- Other KMS providers: Use API keys for authentication
- Custom integrations: Extend the system to support your specific KMS requirements
Credential Management
Q: How can I collect and manage credential data?
A: There are three main approaches:
- Before credential offer creation: Collect all data upfront from external sources (CRM, databases, registries)
- After offer creation, before signing: Use data functions to dynamically enrich credentials with timestamps, DIDs, or external API calls
- During user authentication: Pull verified claims from identity providers during the OID4VCI authorization flow
Q: How do I handle credential revocation and status management?
A: In the Community Stack, you can issue credentials with status information, but you're responsible for hosting and managing the status credentials externally. The Enterprise Stack includes built-in credential status management with support for standards like Bitstring Status List, Token Status List, and StatusList2021.
Q: Can I set expiration dates on credentials?
A: Yes, credentials can include expiration and "valid from" dates. These can be set explicitly during credential creation or generated dynamically using timestamp data functions. This is useful for time-limited credentials like event tickets, student IDs, or transportation passes.
Integration & Development
Q: How do I integrate the Community Stack with my existing systems?
A: The Community Stack is designed for interoperability:
- APIs: RESTful APIs for easy integration
- SDKs: Kotlin/Java libraries for direct integration
- External services: Support for existing KMS, identity providers, and data storage
Q: What programming languages are supported?
A: The Community Stack supports:
- Kotlin/Java: Primary SDK support
- Any language: Via REST APIs
- Future support: Additional languages planned
Q: How do I customize credential appearance in wallets?
A: Credential branding can be configured in two ways:
- Issuer metadata: Define consistent styling per credential type (background color, logo, description)
- Embedded branding: Include visual attributes directly in individual credentials for personalized presentation
Q: What if I need to support a new credential format not currently supported?
A: The walt.id system is built for extensibility. New credential formats can be added as dedicated Kotlin libraries and integrated through the shared digital-credential abstraction layer. Contact us at tamino@walt.id for more information.
Troubleshooting
Q: The services won't start. What should I check?
A: Common issues include:
- Docker not running: Ensure Docker is installed and running
- Port conflicts: Check if ports 7001, 7002, 7003, 7101, 7102 are available
- Configuration files: Verify config files are properly mounted and formatted
Q: How do I monitor the health of my Community Stack deployment?
A: The Community Stack provides:
- Health check endpoints:
/livez
endpoints on all APIs - Docker logs: Container-level logging for deployment issues
Compliance & Standards
Q: Is the Community Stack compliant with eIDAS2 requirements?
A: The Community Stack is continiously aligned with the EU's emerging digital ID ecosystem under eIDAS2, including ARF and implementing acts. This ensures credentials can be issued to different wallets, including EUDI wallets.
Ecosystem Support
Q: What identity ecosystems does the Community Stack support?
A: The Community Stack supports multiple ecosystems including:
- EBSI: European Blockchain Services Infrastructure
- cheqd: Decentralized identity network
- eIDAS2: EU digital identity framework
- iota: Distributed ledger technology
- Custom ecosystems: Extensible for proprietary or new ecosystems
Q: How do I integrate with a specific ecosystem?
A: Ecosystem integration typically involves:
- Trust registry setup: Configure trust registries for the ecosystem
- DID method configuration: Set up appropriate DID methods
- Credential schema registration: Register credential schemas with the ecosystem
- Compliance verification: Ensure compliance with ecosystem requirements
Support & Community
Q: Where can I get help with the Community Stack?
A: Several resources are available:
- Documentation: Comprehensive guides and API references
- GitHub: walt.id identity repository for issues and discussions
- Community: Join our community channel for peer support
Q: How do I contribute to the Community Stack?
A: Contributions are welcome:
- GitHub: Submit issues, feature requests, and pull requests
- Testing: Test and report bugs or compatibility issues
- Community: Share use cases and best practices
Still Have Questions?
If you couldn't find the answer to your question here, please:
- Check our comprehensive documentation
- Visit our GitHub repository
- Contact us at tamino@walt.id for specific inquiries