Introduction

Base URL

There are no restrictions put on the base URL location of the implementation. The URL paths used throughout this specification are shown as absolute paths and their base URL MAY be the host name of the server (e.g., example.com), a subdomain (e.g., api.example.com), or a path within that host (e.g., example.com/api).

Authorization

The VC API can be deployed in a variety of networking environments which might contain hostile actors. As a result, conforming VC API servers require conforming VC API clients to utilize secure authorization technologies when performing certain types of requests. Each HTTP endpoint defined in this document specifies whether or not authorization is required when performing a request. With the exception of the class of forbidden authorization protocols discussed later in this section, the VC API is agnostic regarding authorization mechanism.

The VC API is meant to be generic and useful in many scenarios that require the issuance, possession, presentation, and/or verification of Verifiable Credentials. To this end, implementers are advised to consider the following classifications of use cases:

• Public. A Public API is one that can be called with no authorization. Examples include an open witness or timestamp service (a trusted service that can digitally sign a message with a timestamp for an audit trail purpose), or an open retail coupon endpoint ("buy one, get one free"). Public verifiers might also exist as well, to act as an agnostic third party in a trust scenario.
• Permissioned. Permissioned authorization requires the entity making the API call to, for example, have an access control token or a capability URL, or to invoke a capability from a mutually trusted source. These permissions grant access to the API, but make no assumptions about credential subjects, previous interactions, or the like. Permissioned access is particularly useful in service-to-service based workflows, where credential subjects are not directly involved.
• Bound. Bound authorization involves scenarios where the API calls are tightly coupled, linked, or bound to another process, often out-of-band, that has authenticated the holder/subject of the API interaction. These use cases include, but are not limited to, issuance of subject-specific identity claims directly to the subject in question, or verification of credentials to qualify the holder for service at the verifier, for example. Examples of methods to bind activity on one channel to a VC API call include CHAPI (the Credential Handler API), OIDC (OpenID Connect), and GNAP (the Grant Negotiation and Authorization Protocol). Developers implementing bound authorization will need to take steps to ensure the appropriate level of assurance is achieved in the flow to properly protect the binding.

The rest of this section gives examples of the authorization technologies that have been contemplated for use by conforming implementations. Other equivalent authorization technologies can be used. Implementers are cautioned against using non-standard or legacy authorization technologies.

Service Instances

Service configuration is determined by administrators on per instance basis. Instance configuration can include, but is not limited to, credential format, key options, credential status mechanisms, and/or credential templates. Administrators are expected to configure service instances such that `options` included in client requests cannot result in incorrect action or problematic responses by the service.

A coordinator instance can have access to multiple service instances in order to support different use cases. Runtime discovery of service instance configuration is not supported by the VC API as services are expected to be known by the coordinator at the time of coordinator deployment.

Options

Some of the endpoints defined in the following sections accept an `options` object. All properties of the `options` object are OPTIONAL when configuring each instance, as these properties are intended to meet per-deployment needs that might vary. Thus, any given instance configuration MAY prohibit client use of some `options` properties in order to prevent clients from passing certain data to that instance. Likewise, an instance configuration MAY require that clients include some `options` properties.

Options Extensibility

Implementations MAY extend an `options` object with additional properties.

As extension properties are implementation specific, they ought not be mandatory. This is to maintain interoperability by avoiding clients needing to be modified to use a specific implementation.

When adding an extension `options` property, consider whether providing optionality to clients is necessary. If not, using instance configuration to vary API functionality might be a preferable approach.

Content Serialization

All entity bodies in requests and responses sent to or received from the API endpoints defined by this specification MUST be serialized as JSON and include the `Content-Type` header with a media type value of `application/json`.

Handling Unknown Options and Data

Many of the endpoints defined in the following sections receive data and options in request bodies.

Implementations MUST throw an error if an endpoint receives data, options, or option values that it does not understand or know how to process.

API Component Overview

This section gives an overview of all endpoints in the VC-API by the component the endpoint is expected be callable from. If a component does not have a listing below it means the VC-API does not currently specify any endpoints for that component.

Issuer Coordinator

Below are all endpoints expected to be exposed by the Issuer Coordinator, along with the component that is expected to call the endpoint

Issuer Service

Below are all endpoints expected to be exposed by the Issuer Service, along with the component that is expected to call the endpoint

Status Service

Below are all endpoints expected to be exposed by the Status Service, along with the component that is expected to call the endpoint

Verification Service

Below are all endpoints expected to be exposed by the Verification Service, along with the component that is expected to call the endpoint

Holder Service

Below are all endpoints expected to be exposed by the Holder Service, along with the component that is expected to call the endpoint

Workflow Service

Below are all endpoints expected to be exposed by the Workflow Service, along with the component that is expected to call the endpoint

Issuing

The following APIs are defined for issuing a Verifiable Credential:

Verifying

The following APIs are defined for verifying a Verifiable Credential:

Presenting

The following APIs are defined for presenting a Verifiable Credential:

The URL path values exchange-id and transaction-id are meaningful to the server but are opaque to the client. While some server implementations might use values that happen to be human-readable, clients are strongly advised to not assign semantics to any human-readable values.

Workflows and Exchanges

A VC API workflow defines a particular set of steps for exchanging verifiable credentials between two parties across a trust boundary. Each step can involve the issuance, verification, transmission, or presentation of verifiable credentials. Examples of VC API workflows include, but are not limited to:

• Issuing an employee membership credential to an employee who has logged in to a coordinator website.
• Issuing a vehicle title credential after receiving a presentation of a driver's license credential.
• Verification of the presentation of a permanent resident credential.
• Receipt of one or more newly-issued single-use proof of age credentials.

Workflow instances are expected to be created by administrators, for use with, for example, coordinator websites. A workflow instance is created by performing an HTTP POST to the workflow service's `/workflows` endpoint. The HTTP request body includes the configuration for the workflow instance. This includes, but is not limited to, information about the steps that define the workflow and any credential templates that will be used to issue verifiable credentials. The steps that define the workflow might also be templates, enabling additional flexibility. If a workflow involves the issuance of verifiable credentials, or the verification of presentations or credentials, then the workflow instance configuration can include authorization capabilities to use one or more VC API issuer and/or verification services.

Once a workflow instance exists, authorization to create and query particular workflow interactions, called VC API exchanges, can be given to coordinators.

A VC API exchange represents a particular interaction based on a given VC API workflow. The interaction will take place between an exchange client and the workflow service. Exchanges are expected to be transitory, only existing as long as the interaction takes to complete. The workflow service stores state information about each exchange such as whether the exchange is pending, active, or complete, as well as the current step in the workflow, any workflow-specific variables and data, and any verifiable presentations and credentials received while the exchange executes.

An issuer, verifier, or holder coordinator is responsible for creating exchanges. The coordinator creates an exchange by performing an HTTP POST to the `/exchanges` subpath of a chosen workflow, on the workflow service. The HTTP request body includes a time-to-live (TTL) for the exchange and any variables to be used to populate the workflow's templates for the particular exchange. The request body can also include configuration options to enable the exchange to be executed using additional protocols beyond VC API. Once the exchange is created, an exchange URL that identifies the exchange and enables interaction with it is returned to the coordinator.

The exchange URL is given to the exchange client so that it can initiate the exchange. Initiating the exchange does not require any authorization beyond the exchange URL. Depending on the workflow service implementation, exchange URLs can also be capability URLs (i.e., the URL is an unguessable secret such that only whomever is given the URL can initiate the exchange). If the workflow that the exchange is based on requires any additional authorization beyond the possession of the exchange URL, this is to be obtained during the exchange, not at its initiation.

The exchange URL can also be used by the coordinator to query the current state of the exchange as it progresses and to obtain information associated with the exchange that the workflow service has stored. Querying the exchange in this way requires additional authorization that the coordinator is expected to have and that the exchange client is not.

How the exchange URL is transmitted from a coordinator to an exchange client is out of scope for this specification. Known mechanisms for sharing the exchange URL with the client include the Credential Handler API (aka CHAPI), a QR code, or a universal link.

VC API exchanges are designed to be executable using other protocols in addition to the VC API exchange protocol; for example, an exchange could potentially be executable with any of the OID4VCI, OID4VP, DIDComm, and VC API exchange protocols. The protocols supported depend on the complexity of the workflow the exchange is based on, and the options provided by the coordinator when the exchange was created.

The exchange client is expected to initiate the exchange using a protocol that is compatible with how the client received the exchange URL. For example, the exchange URL could have been provided over CHAPI with a protocol identifier indicating that the VC API protocol ought to be used. Alternatively, the exchange URL could be included as the "credential_issuer" in an OID4VCI credential offer, or as the "client_id" of an OID4VP authorization request, indicating that OID4VCI or OID4VP, respectively, ought to be used. This section focuses on how an exchange client uses VC API to interact with the exchange; see Appendix TBD to see how to combine VC API exchanges with other protocols such as OID4VCI, OID4VP, and DIDComm.

Exchanges that are executed using the VC API protocol involve messages sent as request and response bodies over HTTP. Each message consists of a simple JSON object that includes zero or more of the following properties and values:

• `redirectUrl`: A URL that can be used to continue an interaction at another location. One use case for this is to send the user of an exchange client back to a coordinator website after an exchange has completed.
• `verifiablePresentation`: A Verifiable Presentation. This is used by either party in an exchange to provide information to the other party, either because the latter requested it or because the former is simply offering it.
• `verifiablePresentationRequest`: A Verifiable Presentation Request. This is used by either party in an exchange to request information from the other party.

Custom properties and values might also be included, but are expected to trigger errors in implementations that do not recognize them.

To initiate an exchange using the VC API protocol, an exchange client performs an HTTP POST sending a JSON object as the request body. In the simplest case, when the client has no constraints of its own on the exchange — i.e., it has nothing to request from the other party — the JSON object is empty (`{}`). The workflow service responds with its own JSON object in the response body.

If that response object is empty, the exchange is complete and nothing is requested from nor offered to the exchange client. If the object includes `verifiablePresentationRequest`, then the exchange is not yet complete and some additional information is requested, as specified by the contents of the associated verifiable presentation request. If the object includes `verifiablePresentation`, then some information is offered, such as verifiable credentials issued to the holder operating the exchange client or verifiable credentials with information about the exchange server's operator based on the exchange client's request. If the object includes `redirectUrl`, the exchange is complete and the workflow service recommends that the client proceed to another place to continue the interaction in another form.

Many verifiable credential use cases can be implemented using these basic primitives. Either party to an exchange is capable of requesting verifiable presentations and of providing one or more verifiable credentials that might be necessary to establish trust and/or gain authorization capabilities, and either party is capable of presenting credentials that they hold or that they have issued. Specific workflows can be configured to expect specific presentations and credentials and to reject deviations from the expected flow of information. When a workflow service determines that a particular message is not acceptable, it raises an error by responding with a `4xx` HTTP status message and a JSON object that expresses information about the error.

The VC API exchange design approach is layered: it aims to provide a minimal communication message layer and a set of primitives that enable most use cases to be implemented via specific verifiable presentation requests and verifiable credentials at a layer above. See the appendices that follow for examples of workflows and exchanges that use specific verifiable presentation requests and verifiable credentials.

The following APIs are defined for using workflows and exchanges for credential use cases that require crossing trust boundaries:

There is a `ttl` or time-to-live property associated with exchanges created using the /workflows/{localWorkflowId}/exchanges endpoint. This impacts the lifetime of challenges associated with such an exchange: if a challenge is bound to an exchange, the lifetime of that challenge is the `ttl` of the exchange.

sequenceDiagram
    participant H as Holder
    participant W as Holder Coordinator (Wallet)
    participant I as Issuer/Verifier Coordinator
    autonumber
    Note right of H: Start exchange
    W->>I: Initiate
    Note right of W: POST /workflows/123/exchanges/abc — HTTP request to start exchange (e.g., send credentials, get credentials)
    I->>W: Verifiable Presentation Request (VPR)
    Note left of I: VPR includes method of interaction, for purposes of exchange
    W->>I: Verifiable Presentation (VP)
    Note right of W: POST /workflows/123/exchanges/abc — sent via interaction mechanism to meet requirements of exchange
    I->>W: Verifiable Presentation
    Note left of I: VP includes result of exchange (e.g., VCs), or VPR with new interaction request, or error description
          

Error Handling

Error handling and messaging in the VC-API aligns with Problem Details for HTTP APIs [[RFC9457]]. Implementers SHOULD include a status and a title in the error response body relating to the specifics of the endpoint on which the error occurs.

Aligning on error handling and messaging will greatly improve test-suites accuracy when identifying technical friction impacting interoperability.

Implementers should handle all server errors to the best of their capabilities. Endpoints should avoid returning improperly handled 500 errors in production environments, as these may lead to information disclosure.

Relationship between verification, validation and error handling

It is recommended to avoid raising errors while performing verification, and instead gather ProblemDetails objects to include in the verification results.

Types of ProblemDetails

The example `type` URLs will work in the future after VCDM v2.0 becomes a global standard. To ensure the error links to the appropriate location, you can replace the base URL of `https://www.w3.org/TR/vc-data-model` with `www.w3.org/TR/vc-data-model-2.0` for the time being.

          {
            "type": "https://www.w3.org/TR/vc-data-model#CRYPTOGRAPHIC_SECURITY_ERROR",
            "status": 400,
            "title": "CRYPTOGRAPHIC_SECURITY_ERROR",
            "detail": "The cryptographic security mechanism couldn't be verified. This is likely due to a malformed proof or an invalid verificationMethod."
          }
        

Verification Response

Errors and Warnings

          {
            "verified": false,
            "document": verifiableCredential,
            "mediaType": "application/vc",
            "controller": issuer,
            "controllerDocument": didDocument,
            "warnings": [ProblemDetails],
            "errors": [ProblemDetails]
          }