Issuer API FAQs
This page addresses common questions about the walt.id Issuer API for the Community Stack.
General Questions
Q: What is the difference between the Community Stack and Enterprise Stack Issuer APIs?
A: The Community Stack Issuer API is stateless and typically deployed as a single instance via Docker. It's designed for simpler use cases where you manage your own infrastructure. The Enterprise Stack is stateful, supports multiple instances with shared databases, includes a tenant system for B2B scenarios, and provides built-in GUI management tools, lifecycle management, and credential revocation mechanisms.
Q: What credential formats does the Issuer support?
A: The Issuer 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 OID4VCI draft versions are supported?
A: The Issuer supports OID4VCI Draft 11 and Draft 13, with various user flows including Pre-Authorized Code Flow (with or without PIN) and Authorization Code Flow (with ID Token, VP Token, username/password authentication).
Key Management & Security
Q: How does key management work with the Issuer API?
A: The Issuer API is KMS-agnostic and supports integration with external key management solutions like AWS KMS, Azure Key Vault, Google Cloud KMS, Hashicorp Vault, OCI KMS, and others. Private keys never leave the secure KMS environment - the system sends signing payloads to the KMS and receives signatures back. Raw key material is also supported for development and PoC environments.
Q: What cryptographic algorithms are supported for credential signing?
A: The Issuer supports multiple asymmetric key types including ed25519, secp256k1, secp256r1, and RSA. Only asymmetric keys are used for credential issuance to enable public-key cryptographic operations essential for decentralized trust.
Q: How do I integrate with my existing KMS infrastructure?
A: The system supports multiple authentication methods depending on your KMS provider. For cloud environments, you can use automatically assigned roles (like AWS IAM roles) for keyless authentication. API keys are also supported for other KMS providers.
Credential Data & Lifecycle
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 (Enterprise Stack only)
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, with automatic hosting and publishing capabilities.
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 & Deployment
Q: How do I get started with the Issuer API?
A: Start with the getting started guide which covers setup, key management, and basic credential issuance. You can also explore the SDKs for Kotlin/Java integration or the white-label portal for a GUI-based approach.
Q: Can I use the Issuer API with my existing identity infrastructure?
A: Yes, the Issuer API can integrate with external identity providers through the OID4VCI authorization code flow. This allows you to authenticate users through your existing identity systems (Azure AD, Google, Keycloak, etc.) and use verified claims for credential issuance (Enterprise Stack only)
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. Reach out for more info to tamino@walt.id
Compliance & Standards
Q: Is the Issuer API compliant with eIDAS2 requirements?
A: Yes, the Issuer is aligned with the EU's emerging digital ID ecosystem under eIDAS2, including ARF and implementing acts. This ensures credentials can be issued to different wallet, including EUDI wallets.
Q: What compliance standards do the KMS integrations support?
A: The supported KMS solutions employ hardware security modules (HSMs) validated under FIPS 140-2 (often Level 3) and help organizations meet standards including ISO 27001, PCI DSS, SOC 1/2/3, HIPAA, and GDPR. Specific certifications depend on your chosen KMS provider and deployment configuration.