HomeOpenID4VCIEndpoints

Endpoints

The HTTP endpoints that make up an OpenID4VCI implementation, including metadata discovery, token exchange, and credential issuance.

Endpoint Overview

EndpointMethodRequiredDescription
Credential Issuer Metadata/.well-known/openid-credential-issuerGETReturns issuer capabilities, supported credentials, and endpoint URLs.
Authorization Endpoint/authorizeGETStandard OAuth authorization endpoint. Initiates user authentication and consent.
Token Endpoint/tokenPOSTExchanges authorization code or pre-authorized code for access token.
Credential Endpoint/credentialPOSTIssues credentials. Requires access token and proof of possession.
Nonce Endpoint/noncePOSTReturns a fresh c_nonce for proof of possession. Optional.
Deferred Credential Endpoint/deferredPOSTRetrieves credentials when issuance is asynchronous.
Notification Endpoint/notificationPOSTWallet notifies issuer about credential acceptance/rejection.

Issuer Metadata

The metadata endpoint (/.well-known/openid-credential-issuer) returns a JSON document describing the issuer's capabilities and supported credentials.

GET /.well-known/openid-credential-issuer
{
  "credential_issuer": "https://issuer.example.com",
  "authorization_servers": ["https://auth.example.com"],
  "credential_endpoint": "https://issuer.example.com/credential",
  "deferred_credential_endpoint": "https://issuer.example.com/deferred",
  "notification_endpoint": "https://issuer.example.com/notification",
  "credential_configurations_supported": {
    "UniversityDegreeCredential": {
      "format": "jwt_vc_json",
      "scope": "UniversityDegree",
      "cryptographic_binding_methods_supported": ["did:key", "did:jwk"],
      "credential_signing_alg_values_supported": ["ES256"],
      "proof_types_supported": {
        "jwt": {
          "proof_signing_alg_values_supported": ["ES256", "EdDSA"]
        }
      },
      "claims": {
        "given_name": { "display": [{"name": "First Name"}] },
        "family_name": { "display": [{"name": "Last Name"}] },
        "degree": {
          "type": { "display": [{"name": "Degree Type"}] },
          "name": { "display": [{"name": "Degree Name"}] }
        }
      },
      "display": [{
        "name": "University Degree",
        "locale": "en-US",
        "logo": { "uri": "https://issuer.example.com/logo.png" },
        "background_color": "#12107c",
        "text_color": "#FFFFFF"
      }]
    }
  }
}

credential_configurations_supported

Maps credential IDs to their configuration: format, claims, supported cryptographic methods, and display information.

display

UI metadata for rendering credentials: name, logo, colors. Wallets use this to show credential cards.

Credential Endpoint

The main endpoint for credential issuance. Requires a valid access token and a proof of possession.

Request

POST /credential
POST /credential HTTP/1.1
Host: issuer.example.com
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

{
  "credential_configuration_id": "UniversityDegreeCredential",
  "proof": {
    "proof_type": "jwt",
    "jwt": "eyJ0eXAiOiJvcGVuaWQ0dmNpLXByb29mK2p3dCIsImFsZyI6IkVTMjU2Iiwia2lkIjoiZGlkOmtleTp6Nk1raUt...eyJpc3MiOiJkaWQ6a2V5Ono2TWtpS..."
  }
}

Response

200 OK
HTTP/1.1 200 OK
Content-Type: application/json

{
  "credential": "eyJhbGciOiJFUzI1NiIsInR5cCI6InZjK2p3dCIsImtpZCI6ImRpZDprZXk6ejZNa2lLLi4uIn0.eyJpc3MiOiJodHRwczovL2lzc3Vlci5leGFtcGxlLmNvbSIsInN1YiI6ImRpZDprZXk6ejZNa2lLLi4uIiwidmMiOnsiQGNvbnRleHQiOlsiaHR0cHM6Ly93d3cudzMub3JnL25zL2NyZWRlbnRpYWxzL3YyIl0sInR5cGUiOlsiVmVyaWZpYWJsZUNyZWRlbnRpYWwiLCJVbml2ZXJzaXR5RGVncmVlQ3JlZGVudGlhbCJdLCJjcmVkZW50aWFsU3ViamVjdCI6eyJnaXZlbl9uYW1lIjoiQWxpY2UiLCJmYW1pbHlfbmFtZSI6IlNtaXRoIiwiZGVncmVlIjp7InR5cGUiOiJCYWNoZWxvckRlZ3JlZSIsIm5hbWUiOiJDb21wdXRlciBTY2llbmNlIn19fX0.signature",
  "c_nonce": "fGFF7UkhLa",
  "c_nonce_expires_in": 86400
}

Request Parameters

credential_configuration_id
ID from metadata
proof
Proof of possession object
credential_identifier
For batch issuance (optional)

Response Fields

credential
The issued credential (format varies)
c_nonce
New nonce for subsequent requests
c_nonce_expires_in
Nonce lifetime in seconds
transaction_id
For deferred issuance (instead of credential)

Token Response Extensions

OID4VCI extends the standard OAuth token response with additional fields.

Token Response
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "c_nonce": "tZignsnFbp",
  "c_nonce_expires_in": 86400,
  "authorization_details": [
    {
      "type": "openid_credential",
      "credential_configuration_id": "UniversityDegreeCredential",
      "credential_identifiers": ["CivilEngDegree-2024"]
    }
  ]
}

c_nonce

Nonce for proof of possession. Must be included in the JWT proof sent to credential endpoint.

authorization_details

When used instead of scope, contains credential_identifiers for requesting specific credentials.

Credential Offer Proof of Possession