Getting Started
Issuer2 is an open-source HTTP API service for creating, signing, and distributing verifiable digital credentials. It implements the OID4VCI v1.0 specification and introduces a profile-based architecture for streamlined credential issuance. Supported credential formats include W3C VC, SD-JWT VC (IETF), and ISO 18013-5 mDL.
The original issuer service, which supports Draft 11/13 of the OID4VCI specification, remains available for existing projects. For new projects, we recommend using Issuer2 with its profile-based architecture and OID4VCI v1.0 support.
Coming from the original Issuer (v1)? The biggest change is that each credential type must be declared ahead of time as a profile in a config file — including a default issuer key and credential data — and the service must be restarted to pick up new or changed profiles. You no longer need to supply a signing key or credential data with every issuance request, though you can still override either (and more) per-offer at request time via runtimeOverrides. See Core Concepts below.
Supported Standards
| Credential Formats: | SD-JWT VC (IETF), W3C VC (v1.1+, v2.0), ISO 18013-5 mDL |
| Credential Exchange: | OID4VCI (v1.0) |
| Signing Algorithms: | ed25519, secp256k1, secp256r1, RSA |
Setup
If you are new to the stack, the Docker Compose quick start is the fastest way to get running — it spins up the Issuer, Verifier, and Wallet together in one command, which mirrors a real issuance flow. Once running, the API is available at http://localhost:7005.
When running via Docker Compose, the original Issuer (v1) runs on port 7002 and Issuer2 runs on port 7005 to avoid conflicts. When running Issuer2 standalone with Docker, it uses the default port 7002.
- Docker Compose quick start - Spin up the issuer API locally together with the other services. (Recommended for first-time users)
- Run standalone with Docker - Pull and run the issuer container in isolation using the walt.id identity repo. See the configuration reference for available config options.
- Full API reference - Explore all available endpoints via Swagger.
Core Concepts
Profile-Based Issuance
Issuer2 introduces a profile-based architecture that simplifies credential issuance:
- Credential Profiles – Define reusable configurations for each credential type, including issuer keys, credential data templates, selective disclosure settings, and notification webhooks.
- Credential Offers – Create offers from profiles with optional runtime overrides, supporting both pre-authorized and authorization code flows.
Credential Exchange
The Issuer2 API supports credential exchange protocols based on:
- OID4VCI v1.0: Flows such as Pre-Authorized Code Flow (with or without PIN/Transaction Code) and Authorization Code Flow (with external authorization servers like Keycloak).
- mDoc Issuance: Remote issuance of Mobile Driver's Licenses (mDL) and other ISO 18013-5 credentials via OID4VCI (ISO 18013-7).
Credential Data Collection
Flexible data collection options allow populating credentials before or after an offer has been created:
- Before Credential Offer Creation – Provide all subject data upfront when creating the profile or offer.
- After Credential Offer Creation & Before Credential Signing – Enrich credentials dynamically using data functions such as webhooks or timestamps.
- During User Authentication – When using the authorization code flow, the subject can authenticate against an external IdP and the retrieved claims are mapped to credential fields via
idTokenClaimsMapping.
Features
- Credential Profiles - Create and manage reusable credential configurations.
- Credential Offers - Create credential offers from profiles with runtime overrides.
- Data Functions - Populate credentials with dynamic data at claim time.
- Notifications - Configure webhook notifications to stay informed about on the issuance.
Start Issuing
Choose the credential type that matches your use case:
- SD-JWT VC Issuance - Issue IETF SD-JWT Credentials.
- W3C VC Issuance - Issue W3C Verifiable Credentials with JWT signatures.
- mDL Issuance - Issue ISO 18013-5 Mobile Driver's Licenses.