REST API

The wallet-facing OID4VCI protocol endpoints (/.well-known/openid-credential-issuer, /oid4vci/credential, /oid4vci/deferredCredential, /oid4vci/nonce, /oid4vci/notification, and credential-offer read endpoints) are the IDK simple issuer surface. Wallets call those endpoints.

The EDK adds backend/admin endpoints under /api/oid4vci/v1/backend/... for the connector-backed issuance pipeline. These endpoints create and inspect pipeline sessions, push manual attributes or connector fields, approve or fail in-flight issuance, and accept async callback contributions. Automatic OID4VCI integration is still configured through PipelineConfiguration.invocationBindings; REST contribution is only for backend input, admin intervention, and callback ingress.

Quick Reference

Method	Path	Operation
POST	/api/oid4vci/v1/backend/credential/offers	Create a credential offer and optional pre-seeded groups
GET	/api/oid4vci/v1/backend/credential/offers/{correlation_id}	Read offer status
POST	/api/oid4vci/v1/backend/sessions	Initialize a pipeline session
GET	/api/oid4vci/v1/backend/sessions/{correlationId}/attributes	Read the accumulated attributes and connector field names
POST	/api/oid4vci/v1/backend/sessions/{correlationId}/attributes	Contribute compact groups
GET	/api/oid4vci/v1/backend/sessions/{correlationId}/completeness	Evaluate readiness for issuance
POST	/api/oid4vci/v1/backend/sessions/{correlationId}/approve	Approve or reject an awaiting-review session
POST	/api/oid4vci/v1/backend/sessions/{correlationId}/fail	Record a contributor failure
POST	/api/oid4vci/v1/backend/sessions/{correlationId}/callbacks/{callbackToken}	Async callback contribution

All endpoints except callback ingress use the EDK bearer-token policy path. Callback ingress is authenticated by the scoped capability token in the URL.

Lifecycle Integration

The pipeline can run connector invocations at every OID4VCI lifecycle phase:

OID4VCI_START, OID4VCI_AUTHORIZATION, OID4VCI_PRE_AUTHORIZED, OID4VCI_TOKEN, OID4VCI_CREDENTIAL_REQUEST, OID4VCI_PRE_ISSUE, OID4VCI_DEFERRED, OID4VCI_POST_ISSUANCE, and OID4VCI_NOTIFICATION_RECEIPT.

The IDK issuer exposes neutral lifecycle hook arguments. The EDK connector bridge implements that hook and calls the EDK pipeline commands. VDX is the durable registry/admin layer for connector registrations, routes, grants, throttling, and run lineage.

Initialize a Session

POST /api/oid4vci/v1/backend/sessions creates an IssuancePipelineSession. The body carries a pipeline_configuration, optional correlation_id, optional initial_attributes, optional initial_connector_fields, an encryption mode, and TTL.

{
  "pipeline_configuration": {
    "pipelineId": "employee-credential-v2",
    "invocationBindings": [],
    "claimsBindings": [],
    "expectedInitialConnectorFields": ["employee.id"]
  },
  "correlation_id": "offer-123",
  "initial_connector_fields": {
    "employee.id": "E1042"
  },
  "ttl_seconds": 600
}

• Overview
• API reference
• gRPC
• Command

Initial connector fields satisfy connector invocation inputs before any phase produces them.

POST /api/oid4vci/v1/backend/sessions

The full request and response schema is in the API reference, or open the API reference tab to read it inline.

Contribute Groups

POST /api/oid4vci/v1/backend/sessions/{correlationId}/attributes runs issuance.pipeline.contribute-attributes. The request body is compact and connector-native:

{
  "groups": [
    {
      "contributorId": "hr-backend",
      "phase": "oid4vci_credential_request",
      "connectorFields": {
        "employee.id": "E1042"
      },
      "semanticAttributeSets": [
        {
          "bundleId": "eu.europa.ec.eudi.pid.1",
          "values": {
            "given_name": "Alice",
            "family_name": "Smith"
          }
        }
      ],
      "attributes": [
        { "path": "employment.department", "value": "Engineering" }
      ]
    }
  ]
}

contributorId is provenance for manually supplied input. connectorFields are operational inputs for connector invocations. semanticAttributeSets and attributes become AttributeRecord entries in the session bag and can become credential claims through the claims binding.

• Overview
• API reference
• gRPC
• Command

The adapter decodes compact groups to attributes plus connector fields, then runs the named phase.

POST /api/oid4vci/v1/backend/sessions/{correlationId}/attributes

The full request and response schema is in the API reference, or open the API reference tab to read it inline.

Read Attributes

GET /api/oid4vci/v1/backend/sessions/{correlationId}/attributes returns the decrypted attribute bag, status, completed phases, deferral entries, and connector field names available in the session.

• Overview
• API reference
• Command

Restrict this endpoint carefully; the response contains decrypted session data.

GET /api/oid4vci/v1/backend/sessions/{correlationId}/attributes

The full request and response schema is in the API reference, or open the API reference tab to read it inline.

Completeness and Approval

GET /api/oid4vci/v1/backend/sessions/{correlationId}/completeness evaluates whether every credential binding has the required claims. If a binding is deferrable, the protocol can return a deferred credential response while async connector work continues.

POST /api/oid4vci/v1/backend/sessions/{correlationId}/approve records a review decision. APPROVED lets an awaiting-review session continue; REJECTED fails it.

Contributor Failure

POST /api/oid4vci/v1/backend/sessions/{correlationId}/fail records that a named contributor failed:

{
  "contributor_id": "hr-backend",
  "reason": "upstream timeout"
}

• Overview
• API reference
• gRPC
• Command

The pipeline stops waiting on that contributor. If the contributor was required, the session fails.

POST /api/oid4vci/v1/backend/sessions/{correlationId}/fail

The full request and response schema is in the API reference, or open the API reference tab to read it inline.

Create Credential Offer

POST /api/oid4vci/v1/backend/credential/offers accepts the IDK simple issuer offer fields plus EDK preSeededGroups. The pre-seeded attributes are flattened for the IDK offer command; connector fields are passed to the lifecycle hook as initial connector fields for the EDK pipeline.

{
  "issuerId": "pid-issuer",
  "credentialConfigurationIds": ["PidCredential"],
  "preAuthorizedCodeGrant": true,
  "offerTtlSeconds": 600,
  "preSeededGroups": [
    {
      "contributorId": "registration-office",
      "phase": "oid4vci_start",
      "connectorFields": {
        "document.number": "1234567890"
      }
    }
  ]
}

Async Callback

POST /api/oid4vci/v1/backend/sessions/{correlationId}/callbacks/{callbackToken} accepts the same compact groups body as a normal contribution. The endpoint validates the capability token, cross-checks its correlationId and contributorId, pins execution to the deferred phase, and then runs the pipeline contribution.

• Overview
• API reference
• gRPC
• Command

Callback ingress is a connector contribution under capability-token auth.

POST /api/oid4vci/v1/backend/sessions/{correlationId}/callbacks/{callbackToken}

The full request and response schema is in the API reference, or open the API reference tab to read it inline.

Authorization

Policy command ids are:

• issuance.pipeline.init-session
• issuance.pipeline.contribute-attributes
• issuance.pipeline.get-session-attributes
• issuance.pipeline.evaluate-completeness
• issuance.pipeline.approve-session
• issuance.pipeline.record-contributor-failure
• issuance.pipeline.contribute-via-callback
• oid4vci.issuer.createoffer

Use tenant/backend roles for create and contribution operations. Use narrower support/audit roles for readback because decrypted attributes are visible.