VC

VC (protocolsoup-vc)

Image: ghcr.io/parlesec/protocolsoup-vc

When To Use

Use VC service when you want standalone OID4VCI and OID4VP capabilities without the broader federation stack (OAuth, OIDC, SAML).

Runtime Contract

Property	Value
Port	8080
Health	GET /health
API index	GET /api
Credential formats	dc+sd-jwt (SD-JWT VC), jwt_vc_json, jwt_vc_json-ld, ldp_vc (W3C Data Integrity with ecdsa-rdfc-2019 / eddsa-rdfc-2022)
Credential type	UniversityDegreeCredential

Key Endpoints

OID4VCI

• GET /.well-known/openid-credential-issuer/oid4vci — issuer metadata
• POST /oid4vci/offers/pre-authorized — create pre-authorized offer
• POST /oid4vci/offers/pre-authorized/by-value — offer by value
• POST /oid4vci/offers/pre-authorized/deferred — deferred offer
• POST /oid4vci/token — token endpoint
• POST /oid4vci/nonce — nonce endpoint
• POST /oid4vci/credential — credential request
• POST /oid4vci/deferred_credential — deferred credential

OID4VP

• POST /oid4vp/request/create — create authorization request
• GET|POST /oid4vp/request/{requestID} — authorization request
• GET /oid4vp/verifier-attestation/.well-known/openid-configuration — verifier attestation issuer metadata
• GET /oid4vp/verifier-attestation/.well-known/oauth-authorization-server — verifier attestation AS metadata
• GET /oid4vp/verifier-attestation/jwks — verifier attestation issuer JWKS
• POST /oid4vp/response — wallet response (direct_post, direct_post.jwt)
• GET /oid4vp/result/{requestID} — verification result

Configuration

Variable	Required	Default	Description
SHOWCASE_BASE_URL	Yes	http://localhost:8080	External URL for issuer/verifier metadata
SHOWCASE_CORS_ORIGINS	No	http://localhost:3000,http://localhost:5173	Allowed browser origins
SHOWCASE_DATA_DIR	No	-	State directory for wallet credentials and sessions
OID4VP_VERIFIER_ATTESTATION_ISSUER	No	<SHOWCASE_BASE_URL>/oid4vp/verifier-attestation	Issuer URL exposed for verifier_attestation metadata and JWKS
OID4VP_VERIFIER_ATTESTATION_CLIENT_ID	No	verifier_attestation:<public-host>	Verifier client ID used when client_id_scheme=verifier_attestation
OID4VP_VERIFIER_ATTESTATION_PRIVATE_KEY_PEM	No	Ephemeral in-memory key	PEM-encoded stable signing key for verifier attestation JWTs and JWKS
OID4VP_X509_SANDNS_CLIENT_ID	No	x509_san_dns:<public-host>	x509_san_dns verifier identifier; must match a DNS SAN in the leaf certificate
OID4VP_X509_SANDNS_CERT_CHAIN_PEM	No	Ephemeral self-signed chain	PEM-encoded certificate chain for x509_san_dns request signing. When unset, an ephemeral CA + leaf chain is auto-generated at startup.
OID4VP_X509_SANDNS_PRIVATE_KEY_PEM	No	Ephemeral key	PEM-encoded private key matching the leaf certificate. When unset, generated alongside the ephemeral chain.

Run

docker run -p 8080:8080 \
  -e SHOWCASE_BASE_URL=http://localhost:8080 \
  -e SHOWCASE_DATA_DIR=/app/data \
  -v vc-data:/app/data \
  ghcr.io/parlesec/protocolsoup-vc:latest

Operational Notes

• Pair with the Wallet service (see Wallet page in this tab) for end-to-end OID4VP testing.
• SHOWCASE_BASE_URL must match your public URL for correct issuer and verifier metadata.
• Wallet credentials persist at {SHOWCASE_DATA_DIR}/vc/wallet_credentials.json.
• Client ID schemes supported: redirect_uri, did:web, verifier_attestation, and x509_san_dns. Both verifier_attestation and x509_san_dns auto-provision ephemeral keys/certificates when their PEM env vars are unset.
• Set OID4VP_VERIFIER_ATTESTATION_PRIVATE_KEY_PEM in production so verifier attestation JWKS and signed request objects remain verifiable across restarts and deploys.
• Set OID4VP_X509_SANDNS_CERT_CHAIN_PEM and OID4VP_X509_SANDNS_PRIVATE_KEY_PEM in production for stable x509_san_dns certificate continuity.