Skip to content
ProtocolSoup

VC

VC (protocolsoup-vc)

Section titled “VC (protocolsoup-vc)”

Image: ghcr.io/parlesec/protocolsoup-vc

When To Use

Section titled “When To Use”

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

Runtime Contract

Section titled “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

Section titled “Key Endpoints”

OID4VCI

Section titled “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

Section titled “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

Section titled “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

Section titled “Run”
Terminal window
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

Section titled “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.