VCALM v0.9

A coordinator executes the business rules and policies set by the associated role. Often this is a custom or proprietary coordinator developed specifically for a single party acting in that role; it is the integration glue that connects the controlling party to the verifiable credential ecosystem.

Coordinators might provide a visual user interface, depending on the implementation. Pure command-line or continuously running services might also be able to realize this component.

With the exception of the status service, all role-to-role communication is between coordinators acting on behalf of its particular actor to fulfill its role.

An issuer coordinator executes the rules about who gets what credentials, including how the parties creating or receiving those credentials are authenticated and authorized. Typically the issuer coordinator integrates the issuer's back-end system with the issuer service. This integration uses whatever technologies are appropriate; the interfaces between the issuer coordinator and back-end services are out of scope for this specification. The issuer coordinator drives the issuer service.

A verifier coordinator communicates with a verifier service to first check authenticity and timeliness of a given verifiable credential or verifiable presentation, then applies the verifier's business rules before ultimately accepting or rejecting that verifiable credential or verifiable presentation. Such business rules might include evaluating the issuer of a particular claim or simply checking a configured allow-list. The verifier coordinator exposes an API for submitting verifiable credentials to the verifier per the verifier's policies. For example, the verifier coordinator might only accept verifiable credentials from current users of the verifier's other services. These rules typically require bespoke integration with the verifier's existing back-end.

A holder coordinator executes the business rules for approving the flow of credentials under the control of the holder, from issuers to verifiers. In some deployments this means exposing a user interface that gives individual holders a visual way to authorize or approve verifiable credential storage or transfer. Some functionality of the holder coordinator is commonly referred to as a digital wallet. In this API, the holder coordinator initiates all flows. They request verifiable credentials from issuers. They decide if, and when, to share those verifiable credentials with verifiers. Within this API, there is no way for either the issuer or the verifier to initiate the transfer of a verifiable credential. In many scenarios, the holder coordinator is expected to be under the control of an individual human, ensuring a person is directly involved in the communication of verifiable credentials, even if only at the step of authorizing the transfer. However, some verifiable credentials are about organizations, not individuals. How individuals using holder coordinators related to organizations, and in particular, how organizational credentials are securely shared with, and presented by, (legal) agents of those organizations is not in scope for this specification.

A service provides lower-level API functionality, driven by its associated coordinator, and is designed to enable infrastructure providers to offer verifiable credential capability through service delivery architectures such as Software-as-a-Service. All services expose HTTP endpoints to their authorized coordinators, which are themselves operating on behalf of an associated role. Although deployed services might provide their own HTML interfaces, such interfaces are out of scope for this specification. Only the HTTP endpoints of services are defined herein.

An issuer service takes requests to issue verifiable credentials from authorized issuer coordinators and return conforming verifiable credentials. This service has access to cryptographic material, such as private keys or key services which utilize private keys, in order to create the proofs for verifiable credentials. The API between the issuer service and its associated cryptographic key management service is out of scope for this specification.

A verifier service takes requests to verify verifiable credentials and verifiable presentations and returns the result of checking their proofs and status (if present). The service only checks the authenticity and timeliness of the verifiable credential, leaving the verifier coordinator to finish applying any necessary business rules.

A holder service takes requests to create Verifiable Presentations from an optional set of verifiable credentials and returns well-formed, signed Verifiable Presentations containing those VCs. These verifiable presentations are used with issuers to demonstrate control over DIDs prior to verifiable credential issuance and with verifiers to present specific VCs.

A status service provides a privacy-preserving means of publishing and checking the status of any Verifiable Credentials issued by the issuer. Implementers of verifier services are encouraged to understand the privacy implications of checking status by referring to the respective status specification used by the verifiable credential. For specific mechanisms by which to manage verifiable credential statuses, it's recommended to refer to well-known external specifications, such as the [VC-BITSTRING-STATUS-LIST].

A storage service is used by each actor in the system to store their own verifiable credentials and corresponding data, as needed. Several known implementations use secure data storage such as encrypted data vaults for storing the holder's verifiable credentials and use cryptographic authorizations to grant access to those verifiable credentials to verifier coordinators, as directed by the holder. In-browser retrieval of such stored credentials can enable web-based verifier coordinators to integrate data from the holder without sharing that data with the verifier—the data is only ever present in the browser. Authorizing third-party remote access to holder storage is likely in-scope for this API, although we expect this to be defined using extensible mechanisms to support a variety of storage and authorization approaches.

The issuer and verifier storage solutions may or may not use secure data storage. Since all such storage interaction is moderated by the bespoke issuer and Storage Coordinators, any necessary integrations can simply be part of that bespoke customization. We expect different implementations to compete on the ease of integration into various back-end storage platforms.

A workflow service provides a way for coordinators to automate specific interactions for specific users. Each role (holder, issuer, and verifier) can run their own workflow service to create and manage exchanges that realize particular workflows. Administrators configure the workflow system to support particular flows. Then, when the business rules justify it, coordinators create exchanges at their workflow service and give access to those exchanges to any authorized party.

An administration service is an acknowledgement that each of the other components need a way to be configured and managed, without prescribing the interfaces or means of that configuration. Some components might use JSON files to drive a command line interface. Others might expose HTML pages. It is expected that different implementations will compete on the power, ease, and flexibility of their administration and therefore, configuration is largely out of scope for this specification. There are some places where some configuration mechanisms are provided, such as in Section 3.6.1 Create Workflow, where there was broad agreement to standardize some configuration parameters. As the market matures, other areas of configuration standardization might occur in future versions of this specification.

The APIs defined in this specification presume that they are attached to a specific instance with an associated configuration that has been put in place by a system administrator. When a client calls an endpoint on a particular instance, the instance uses the configuration and options provided by the client to execute the action.

For example, the /credentials/issue endpoint can be provided at the end of a longer URL such as /instances/12345/credentials/issue. In this case, it is the instance that is configured to know which cryptographic key to use for issuance, whether or not a status list is involved, the type of credential to issue, the credential format, and what additional options are possible on the endpoint.

Software clients that call a particular instance might not have the capability to configure an instance, or be aware of the setup that the administrator did on the instance other than the requisite details to make appropriate use of it. Administration endpoints for configuring instances could be provided by implementations but are not necessarily exposed as HTTP APIs; configuration can also be done through configuration files or graphical interfaces.

Each coordinator or service instance is associated with a specific configuration that drives its behavior. This section contains how some of those configurations might be performed.

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.

The following APIs are defined for issuing a Verifiable Credential:

The following APIs are defined for verifying a Verifiable Credential:

When working with verifiable credentials, and decentralized identifier-based authentication, one party often needs to request data from another. This section describes the general format of those requests and provides a concrete verifiable presentation request format as well.

{
  // one or more requests for verifiable credentials
  "query": [{
    "type": "QueryByExample",
    // query details specific to QueryByExample...
  }],
  // The target security domain, such as a website domain, to include in
  // the verifiable presentation
  "domain": "domain.example",

  // The random challenge string to include in the verifiable presentation
  "challenge": "f63cb0d2-760e-11f0-a2b1-67febb854a5f"
}

{
  "query": [{
    "type": "QueryByExample",
    "credentialQuery": [{
      // (Optional) Reason for requesting this credential that
      // may be shown to a user by their software
      "reason": "We need to know if you are an alumni of this school.",
      // (Mandatory) An example of the credential being requested
      "example": {
        "@context": [
          "https://www.w3.org/ns/credentials/v2",
          "https://www.w3.org/ns/credentials/examples/v2"
        ],
        "type": "ExampleAlumniCredential",
        // (Optional) Select credential based on credential subject type
        "credentialSubject": {
          "type": "Alumni"
        }
      },
      // (Optional) Specify credentials from a particular authority or
      // delegate of the authority
      "authority": [{
        "issuer": "did:web:authority.example"
      }]
    }]
  }],
  "challenge": "3182bdea-63d9-11ea-b6de-3b7c1404d57f",
  "domain": "reunion.example"
}

{
  "query": [{
    "type": "DIDAuthentication",
    "acceptedMethods": [{"method": "example"}]
  }],
  "challenge": "99612b24-63d9-11ea-b99f-4f66f3e4f81a",
  "domain": "example.com"
}

{
  "@context": ["https://www.w3.org/ns/credentials/v2"],
  "type": "VerifiablePresentation",
  "holder": "did:example:12345",
  "proof": {
    "type": "DataIntegrityProof",
    "cryptosuite": "eddsa-rdfc-2022",
    "verificationMethod": "did:example:12345#key-1",
    "challenge": "99612b24-63d9-11ea-b99f-4f66f3e4f81a",
    "domain": "example.com",
    "created": "2024-02-25T14:58:42Z",
    "proofPurpose": "authentication",
    "proofValue": "z3FXQjecWufY46...UAUL5n2Brbx"
  }
}

{
  "query": [{
    "type": "DIDAuthentication",
    "acceptedMethods": [{"method": "key"}],
    "acceptedCryptosuites": [{"cryptosuite": "ecdsa-rdfc-2019"}]
  }],
  "challenge": "99612b24-63d9-11ea-b99f-4f66f3e4f81a",
  "domain": "example.com"
}

{
  "query": [{
    "type": "DIDAuthentication",
    "acceptedMethods": [{"method": "key"}, {"method": "web"}],
    "acceptedCryptosuites": [{"cryptosuite": "ecdsa-rdfc-2019"}]
  }, {
    "type": "DIDAuthentication",
    "required": false,
    "acceptedMethods": [{"method": "key"}, {"method": "web"}],
    "acceptedCryptosuites": [{"cryptosuite": "bbs-2023"}]
  }],
  "challenge": "zLEwtBYgQVNR4tyeo",
  "domain": "didauth.example"
}

{
  "@context": ["https://www.w3.org/ns/credentials/v2"],
  "type": "VerifiablePresentation",
  "holder": "did:example:12345",
  "proof": {
    "type": "DataIntegrityProof",
    "cryptosuite": "eddsa-rdfc-2022",
    "verificationMethod": "did:example:12345#key-1",
    "challenge": "99612b24-63d9-11ea-b99f-4f66f3e4f81a",
    "domain": "example.com",
    "created": "2024-02-25T14:58:42Z",
    "proofPurpose": "authentication",
    "proofValue": "z3FXQjecWufY46...UAUL5n2Brbx"
  }
}

{
  "query": [{
    "type": "AuthorizationCapabilityQuery",
    "capabilityQuery": [{
      "referenceId": "a-memorable-name",
      "allowedAction": ["read", "write"],
      "controller": "did:example:1234",
      "invocationTarget": {
        "type": "urn:edv:documents"
      }
    }, {
      "referenceId": "another-memorable-name",
      "allowedAction": "sign",
      "controller": "did:example:1234",
      "invocationTarget": {
        "type": "Multikey",
        "proofPurpose": "assertionMethod"
      }
    }],
    challenge: "111112b24-63d9-11ea-b99f-4f66f3e4f81a"
  }]
}

{
  "query": [{
    "type": "QueryByExample",
    "group": "certification",
    // query details ...
  },
  // "AND"
  {
    "type": "DigitalCredentialQueryLanguage",
    "group": "certification",
    // query details ...
  }]
}

{
  "query": [{
    "type": "QueryByExample",
    "group": "college-degree",
    // query details ...
  },
  // "OR"
  {
    "type": "DigitalCredentialQueryLanguage",
    "group": "job-experience",
    // query details ...
  }]
}

The following APIs are defined for presenting a Verifiable Credential:

The URL path value exchange-id is meaningful to the server but is 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.

A 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, and/or presentation of verifiable credentials. Workflows are designed to support both linear sequences of steps and more complex patterns including branching logic and repeated steps, enabling sophisticated interactions between the parties involved. Examples of VC API workflows include, but are not limited to, the following:

• 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 issuer and/or verification services.

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

An exchange represents a particular interaction based on a given 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. Implementers are free to use whatever variables they desire for their implementation in addition to the reserved variables defined in Section 3.6.3 Create Exchange. While there is no technical limitation on the number of steps in a workflow, implementers might want to enforce a default maximum number of steps to prevent bugs.

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 an expiration date and time 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 this 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. Note that while the exchange URL is given to the coordinator to then provide it to the exchange client, the actual exchange is performed between the exchange client and the workflow service; the coordinator is not involved after providing the exchange URL to the exchange client. To be clear: a coordinator can still use its own exchange client for any use case that requires it to execute the exchange itself.

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.

Exchanges are designed to be executable using other protocols in addition to this API exchange protocol; for example, an exchange could potentially be executable with any of the OID4VCI, OID4VP, DIDComm, and 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 this 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 this API to interact with the exchange; see Appendix TBD to see how to combine exchanges with other protocols such as OID4VCI, OID4VP, and DIDComm.

Exchanges that are executed using this 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 this 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 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.

A given interaction with an exchange is expected to be short-lived but other mechanisms can be used to enable longer or multi-stage interactions. Examples of other interaction mechanisms include SMS, email, web notifications, or phone calls. This approach simplifies digital wallet implementation and allows existing mechanisms to be reused without reinvention within this API. The Web or native platforms are expected to enable additional interactions via applications (such as Web browsers) or other platform features. For example, in asynchronous issuance, a holder requests a credential but waits for processing. In such cases, system components (such as an issuer coordinator) make use of mechanisms outside this API to notify the holder when their credential is ready for collection.

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

In the workflows and exchanges APIs, a "local" ID refers to an ID that is local to a service instance. In other words, an exchangeId or workflowId refers to a fully qualified URL, while a localExchangeId or localWorkflowId refers to a specific element in the URL path.

{
  "id": "9fd3bc6d-4a04-4b3d-a983-3482d0586626",
  "initialStep": "didAuthRequest",
  "steps": {
    "didAuthRequest": {
      "createChallenge": true,
      "verifiablePresentationRequest": {
        "query": {
          "type": "DIDAuthentication",
          "acceptedMethods": [
            {
              "method": "key"
            },
            {
              "method": "web"
            }
          ],
          "acceptedCryptosuites": [
            {
              "cryptosuite": "eddsa-rdfc-2022"
            },
            {
              "cryptosuite": "ed25519-2020"
            }
          ]
        },
        "domain": "https://issuer.example.com"
      },
      "nextStep": "credentialDelivery"
    },
    "credentialDelivery": {
      "issueRequests": [
        {
          "credentialTemplateId": "caffb919-053a-4bfa-beba-80567904f842",
          "variables": "sampleAchievementCredential"
        }
      ]
    }
  },
  "credentialTemplates": [
    {
      "id": "caffb919-053a-4bfa-beba-80567904f842",
      "type": "jsonata",
      "template": "{
        \"credential\": {
          \"@context\": [
            \"https://www.w3.org/ns/credentials/v2\",
            \"https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.3.json\",
            \"https://purl.imsglobal.org/spec/ob/v3p0/extensions.json\"
          ],
          \"id\": sampleAchievementCredential.id,
          \"type\": [\"VerifiableCredential\", \"AchievementCredential\"],
          \"issuer\": {
            \"type\": [\"Profile\"],
            \"name\": \"Example Issuer\",
            \"image\": {
              \"type\": \"Image\",
              \"id\": \"https://issuer.example.com/logo.png\"
            }
          },
          \"awardedDate\": sampleAchievementCredential.awardedDate,
          \"validFrom\": sampleAchievementCredential.validFrom,
          \"name\": \"Sample Achievement\",
          \"credentialSubject\": {
            \"id\": results.didAuthRequest.verifiablePresentation.holder,
            \"type\": \"AchievementSubject\",
            \"name\": sampleAchievementCredential.credentialSubject.name,
            \"achievement\": {
              \"id\": sampleAchievementCredential.credentialSubject.achievement.id,
              \"type\": [\"Achievement\"],
              \"achievementType\": sampleAchievementCredential.credentialSubject.achievement.achievementType,
              \"name\": sampleAchievementCredential.credentialSubject.achievement.name,
              \"description\": sampleAchievementCredential.credentialSubject.achievement.description,
              \"alignment\": sampleAchievementCredential.credentialSubject.achievement.alignment
            }
          }
        }
      }"
    }
  ],
  "controller": "did:web:issuer.example.com"
}

{
  "id": "9fd3bc6d-4a04-4b3d-a983-3482d0586626",
  "initialStep": "didAuthRequest",
  "steps": {
    "didAuthRequest": {
      "stepTemplate": {
        "type": "jsonata",
        "template": "{
          "createChallenge": true,
          "verifiablePresentationRequest": verifiablePresentationRequest,
          "callback": {
            "url": callbackUrl
          },
          "nextStep": "credentialDelivery"
        }"
      }
    },
    "credentialDelivery": {
      "issueRequests": [
        {
          "credentialTemplateId": "caffb919-053a-4bfa-beba-80567904f842",
          "variables": "sampleAchievementCredential"
        }
      ]
    }
  },
  "credentialTemplates": [
    {
      "id": "caffb919-053a-4bfa-beba-80567904f842",
      "type": "jsonata",
      "template": "{
        \"credential\": {
          \"@context\": [
            \"https://www.w3.org/ns/credentials/v2\",
            \"https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.3.json\",
            \"https://purl.imsglobal.org/spec/ob/v3p0/extensions.json\"
          ],
          \"id\": sampleAchievementCredential.id,
          \"type\": [\"VerifiableCredential\", \"AchievementCredential\"],
          \"issuer\": {
            \"type\": [\"Profile\"],
            \"name\": \"Example Issuer\",
            \"image\": {
              \"type\": \"Image\",
              \"id\": \"https://issuer.example.com/logo.png\"
            }
          },
          \"awardedDate\": sampleAchievementCredential.awardedDate,
          \"validFrom\": sampleAchievementCredential.validFrom,
          \"name\": \"Sample Achievement\",
          \"credentialSubject\": {
            \"id\": results.didAuthRequest.verifiablePresentation.holder,
            \"type\": \"AchievementSubject\",
            \"name\": sampleAchievementCredential.credentialSubject.name,
            \"achievement\": {
              \"id\": sampleAchievementCredential.credentialSubject.achievement.id,
              \"type\": [\"Achievement\"],
              \"achievementType\": sampleAchievementCredential.credentialSubject.achievement.achievementType,
              \"name\": sampleAchievementCredential.credentialSubject.achievement.name,
              \"description\": sampleAchievementCredential.credentialSubject.achievement.description,
              \"alignment\": sampleAchievementCredential.credentialSubject.achievement.alignment
            }
          }
        }
      }"
    }
  ],
  "controller": "did:web:issuer.example.com"
}

{
  "response_type": "vp_token",
  "presentation_definition": {
    "id": "f1bd224a-0fed-469a-b64a-dad7cf63fd98",
    "input_descriptors": [
      {
        "id": "77d50c71-95ef-442c-a372-f32e17634fab",
        "constraints": {
          "fields": [
            {
              "path": [
                "$['@context']"
              ],
              "filter": {
                "type": "array",
                "contains": {
                  "type": "string",
                  "const": "https://www.w3.org/ns/credentials/v2"
                }
              }
            },
            {
              "path": [
                "$['type']"
              ],
              "filter": {
                "type": "array",
                "contains": {
                  "type": "string",
                  "const": "VerifiableCredential"
                }
              }
            },
            {
              "path": [
                "$['credentialSubject']['name']"
              ],
              "filter": {
                "type": "string"
              }
            }
          ]
        },
        "purpose": "We require a name credential to display your name when you post messages."
      }
    ]
  },
  "response_mode": "direct_post",
  "client_metadata": {
    "vp_formats_supported": {
      "ldp_vc": {
        "proof_type_values": [
          "DataIntegrityProof",
          "Ed25519Signature2020"
        ],
        "cryptosuite_values": [
          "ecdsa-rdfc-2019",
          "eddsa-rdfc-2022"
        ]
      }
    },
    "vp_formats": {
      "jwt_vp": {
        "alg": [
          "EdDSA",
          "Ed25519",
          "ES256",
          "ES384"
        ]
      },
      "jwt_vp_json": {
        "alg": [
          "EdDSA",
          "Ed25519",
          "ES256",
          "ES384"
        ]
      },
      "di_vp": {
        "proof_type": [
          "ecdsa-rdfc-2019",
          "eddsa-rdfc-2022",
          "Ed25519Signature2020"
        ]
      },
      "ldp_vp": {
        "proof_type": [
          "ecdsa-rdfc-2019",
          "eddsa-rdfc-2022",
          "Ed25519Signature2020"
        ]
      }
    }
  },
  "client_id": "https://some.example/workflows/z1A7ojitBF3pGpVzW17MgU7zm/exchanges/z1ACKwiBiXmuGjpKAdKMpBZXB/openid/client/authorization/response",
  "client_id_scheme": "redirect_uri",
  "response_uri": "https://some.example/workflows/z1A7ojitBF3pGpVzW17MgU7zm/exchanges/z1ACKwiBiXmuGjpKAdKMpBZXB/openid/client/authorization/response",
  "nonce": "z1ACKwiBiXmuGjpKAdKMpBZXB"
}

There is an expires property associated with exchanges, denoting the expiration date and time of the exchange. It is 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, that challenge ceases to be valid at the date referenced by the expires property of the exchange.

It is useful for an implementation to communicate how to start interacting with it to another implementation. This bootstrapping process is called initiating an interaction, and communicates what protocols each implementation supports as well as how to start a particular interaction with the implementation.

The sequence diagram below outlines an issuer generating an interaction URL, using a QR Code to share it with a holder, and proceeding with the vcapi protocol:

The sequence diagram below outlines a verifier generating an interaction URL, using a QR Code to share it with a holder, and proceeding with the vcapi protocol:

The sequence diagram below outlines a holder generating an interaction URL, using a QR Code to share it with a verifier, and proceeding with the inviteRequest protocol:

https://app.example/interactions/z8n38Dp7a?iuv=1

3.7.2 Interaction QR Code Format

An interaction QR Code MUST be an interaction URL expressed as a QR code according to ISO18004:2024: QR Code Bar Code Symbology Specification. To ensure broad interoperability, the length of the interaction URL SHOULD be as short as possible, SHOULD NOT exceed 400 alphanumeric characters, and MUST NOT exceed 4,296 alphanumeric characters. An example of an interaction QR code can be found below:

{
  "protocols": {
    "inviteRequest": "https://saas.example/workflows/123/exchanges/987/invite-request/response",
    "vcapi": "https://saas.example/workflows/123/exchanges/987",
    "OID4VP": "openid4vp://?client_id=https%3A%2F%2Fapp.example%2Fworkflows%2F123%2Fexchanges%2F987%2Fopenid%2Fclient%2Fauthorization%2Fresponse&request_uri=https%3A%2F%2Fapp.example%2Fworkflows%2F123%2Fexchanges%2F987%2Fopenid%2Fclient%2Fauthorization%2Frequest'"
  }
}

{
  "protocols": {
    "inviteRequest": "https://saas.example/interactions/123/invite-request/response"
  }
}

{
  "url": "https://website.example/checkout/8372974",
  "purpose": "Checkout at ShopCo",
  "referenceId": "417bcaf2-14d9-11f0-99d7-9f094678517b"
}

{
  "url": "https://website.example/forms/7864165",
  "purpose": "Fill out online form",
  "referenceId": "d4a6e5b8-1715-4654-8e47-e68b311756d1"
}

{
  "verifiablePresentationRequest": {
    "query": [{
      "type": "QueryByExample",
      "credentialQuery": [{
        "reason": "Please provide your student ID.",
        "example": {
          "@context": [
            "https://www.w3.org/ns/credentials/v2",
            "https://www.w3.org/ns/credentials/examples/v2",
          ],
          "type": "StudentIdCredential",
          "credentialSubject": {
            "studentId": ""
          },
        },
        "trustedIssuer": [{
          "issuer": "did:web:university.example"
        }]
      }]
    }],
    "challenge": "5e34826e-14da-11f0-98a5-8b1c0a196728",
    "domain": "university.example"
  }
}

When an implementation detects an anomaly while processing a document, a ProblemDetails object can be used to report the issue to other software systems. The interfaces for these objects follow [RFC9457] to encode the data. A ProblemDetails map consists of the following properties:

type

The type key MUST be present and its value MUST be a URL identifying the type of problem.

title

The title key SHOULD provide a short but specific human-readable string for the problem.

detail

The detail key SHOULD provide a longer human-readable string for the problem.

Leveraging keys such as detail, and instance is encouraged, to provide more contextual feedback about the error, while being conscious of security concerns and hence not disclosing sensitive information.

The following problem description types are defined by this specification:

https://www.w3.org/TR/vcalm#UNKNOWN_OPTION_PROVIDED

An option that is unknown to the implementation was provided to the API call.

Further lists of ProblemDetails that might be reported by implementations can be found in the following specifications:

• Section 7.2: Problem Details in the Verifiable Credentials Data Model v2.0 specification.
• Section 4.7: Processing Errors in the Verifiable Credential Data Integrity 1.0 specification.
• Section 3.5: Processing Errors in the Bitstring Status List v1.0 specification.

{
  "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."
}

Implementers are strongly advised to sanitize all server errors in production environments, as not doing so can lead to information disclosure.

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

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