Try our Chrome extension
Easily add the current web-page from your browser directly into your changedetection.io tool, more great features coming soon!
Chrome Webstore
Changedetection.io needs your support!
You can help us by supporting changedetection.io on these platforms;
- Rate us at AlternativeTo.net
- Star us on GitHub
- Follow us at Twitter/X
- G2 Software reviews
- Check us out on LinkedIn
- And tell your friends and colleagues :)
The more popular changedetection.io is, the more time we can dedicate to adding amazing features!
Many thanks :)
changedetection.io team
Not yet seconds ago
False
Not yet seconds ago
1 year ago
| ReSpec * 🔎 Search Specref… * 📚 Search definitions… * ℹ️ About 35.5.1… * 💾 Export… 2 Below are all endpoints expected to be exposed by the issuer coordinator, along with the component that is expected to call the endpoint Endpoint Expected Caller 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 Endpoint Expected Caller POST /credentials/issue Issuer Coordinator GET /credentials/{id} Issuer Coordinator DELETE /credentials/{id} Issuer Coordinator, Holder Coordinator 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 Endpoint Expected Caller POST /credentials/status Issuer Service 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 Endpoint Expected Caller POST /credentials/verify Verification Coordinator POST /presentations/verify Verification Coordinator POST /challenges Verification Coordinator 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 Endpoint Expected Caller POST /credentials/derive Holder Coordinator GET /credentials/{id} Issuer Coordinator DELETE /credentials/{id} Issuer Coordinator, Holder Coordinator GET /presentations Holder Coordinator POST /presentations Holder Coordinator GET /presentations/{id} Holder Coordinator DELETE /presentations/{id} Holder Coordinator 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 Endpoint Expected Caller POST /workflows Administrators GET /workflows/{localWorkflowId} Administrators POST /workflows/{localWorkflowId}/exchanges Owner Coordinator GET /workflows/{localWorkflowId}/exchanges/{localExchangeId} Owner Coordinator POST /workflows/{localWorkflowId}/exchanges/{localExchangeId} Anyone Issuing The following APIs are defined for issuing a Verifiable Credential: Endpoint Description GET /credentials/{id} Gets a credential or verifiable credential by ID. To get a credential that does not have credential.id set but has an associated credentialId value, pass credentialId instead. DELETE /credentials/{id} Deletes a credential or verifiable credential by ID. To delete a credential that does not have credential.id set but has an associated credentialId value, pass credentialId instead. POST /credentials/issue Issues a credential and returns it in the response body. POST /credentials/status Updates the status of an issued credential Issue Credential This endpoint is used to issue a verifiable credential. Note : Issued credential media types To issue credentials with a media type other than application/vc — such as application/mdoc, application/vc+sd-jwt, application/vcb;barcode-format=qr_code, or application/vcb;barcode-format=pdf417 — an EnvelopedVerifiableCredential can be returned in the response. POST /credentials/issue - Issues a credential and returns it in the response body. The /credentials/issue endpoint uses the following schema when receiving a POST: Property Description credential [object] A W3C Verifiable Credential intended for issuance. It MUST be an object of the following form: @context [array]The JSON-LD context of the credential. Each item in the @context array MUST be a string.id [string]The ID of the credential. type [array]The JSON-LD type of the credential. Each item in the type array MUST be a string.issuer [object]Either a string or an object of the following form: id [string]The issuer id. validFrom [string]The validFrom date validUntil [string]The validUntil date credentialSubject [object]an objectproof [object]Either an object or { "type": "array", "items": { "type": "object" } } options [object] Options for specifying how a credential is issued. It MUST be an object of the following form: mandatoryPointers [array]Used with selective disclosure schemes to specify mandatory reveal statements Each item in the mandatoryPointers array MUST be a string.credentialId [string]A URI that can be used to identify the credential, that can be used in APIs to refer to the issued verifiable credential. If credentialId is not provided by the issuer coordinator, the issuer service will auto-populate its value from credential.id. If neither credentialId nor credential.id is provided, it will not be possible to refer to this credential once issued nor to deal with errors of duplication. credentialId SHOULD NOT be set by the issuer coordinator if the credential.id property is set, nor should credentialId be used as a replacement for credential.id; rather, credentialId is a means of identifying a credential without the id property (i.e., credential.id) being set. The issuer service SHOULD NOT auto-generate a credentialId if one is not supplied by the issuer coordinator, because doing so could create a partitioning error if the result is never received by the client. The /credentials/issue endpoint can result in any of these responses when receiving a POST: Response Body 201 Credential successfully issued! an object of the following form: IssueCredentialResponse [object]The format returned from a successful request for a verifiable credential. It MUST be an object of the following form: verifiableCredential [object]Either an object of the following form: @context [array]The JSON-LD context of the credential. Each item in the @context array MUST be a string.id [string]The ID of the credential. This property MAY be empty. The issuer SHOULD NOT auto-generate the id property if not provided, as a Verifiable Credential does not require the id property to be valid, and there are use cases for which the id property cannot be set. type [array]The JSON-LD type of the credential. Each item in the type array MUST be a string.issuer [object]Either a string or an object of the following form: id [string]The issuer id. issuanceDate [string]The issuanceDate expirationDate [string]The expirationDate credentialSubject [object]an objectproof [object]A Data Integrity Proof as defined by the W3C VC Data Integrity specification. It MUST be an object of the following form: type [string]Data Integrity Proof type. cryptosuite [string]The name of the cryptographic suite. created [string]Date the proof was created. nonce [string]A value chosen by the creator of a proof to randomize proof values for privacy purposes. verificationMethod [string]Verification Method used to verify proof. proofPurpose [string]The purpose of the proof to be used with verificationMethod. proofValue [string]Value of the Linked Data proof. or An object used to associate an enveloped verifiable credential with the verifiableCredential property in a verifiable presentation. It MUST be an object of the following form: @context [array]The JSON-LD context of the enveloped verifiable credential. Each item in the @context array MUST be a string.id [string]This MUST be a "data:" scheme URL [RFC2397] that expresses a secured verifiable credential using an enveloping security scheme. type [string]This MUST be EnvelopedVerifiableCredential. content-type: application/json 400 The request could not be processed due to one of the following reasons: - The provided value of 'issuer' does not match the expected configuration. - Another condition that results in a Bad Request. If a use case requires an issuer instance to attach multiple proofs to the provided credential, the instance MUST attach all of these proofs in response to a single call to the /credentials/issue endpoint. If a provided credential already contains one or more proofs, the behavior is determined by the configuration of the issuer instance. An issuing instance SHOULD be configured to handle existing proofs in one of the following ways: * Proof Sets: Append new proofs to the list of existing proofs provided by the caller, first converting any existing single proof to a list if necessary. Here there is no binding to any existing proofs; the new proofs exist in parallel with those previously provided by the caller. * Proof Chains: Append new proofs to create or extend an existing proof chain. Here proofs are linked in a specific sequence, potentially using the previousProof property to establish the chain relationship. * Error Handling: Return an error if credential values that contain existing proof values are provided, when the instance is configured to only accept credentials without existing proofs. The specific approach used depends on the configuration of the issuer instance and the intended use case for the verifiable credential. Get a Specific Credential GET /credentials/{id} - Gets a credential or verifiable credential by ID. To get a credential that does not have credential.id set but has an associated credentialId value, pass credentialId instead. The /credentials/{id} endpoint can result in any of these responses when receiving a GET: Response Body 200 Credential retrieved The format returned from a successful request for a verifiable credential. It MUST be an object of the following form: verifiableCredential [object]Either an object of the following form: @context [array]The JSON-LD context of the credential. Each item in the @context array MUST be a string.id [string]The ID of the credential. This property MAY be empty. The issuer SHOULD NOT auto-generate the id property if not provided, as a Verifiable Credential does not require the id property to be valid, and there are use cases for which the id property cannot be set. type [array]The JSON-LD type of the credential. Each item in the type array MUST be a string.issuer [object]Either a string or an object of the following form: id [string]The issuer id. issuanceDate [string]The issuanceDate expirationDate [string]The expirationDate credentialSubject [object]an objectproof [object]A Data Integrity Proof as defined by the W3C VC Data Integrity specification. It MUST be an object of the following form: type [string]Data Integrity Proof type. cryptosuite [string]The name of the cryptographic suite. created [string]Date the proof was created. nonce [string]A value chosen by the creator of a proof to randomize proof values for privacy purposes. verificationMethod [string]Verification Method used to verify proof. proofPurpose [string]The purpose of the proof to be used with verificationMethod. proofValue [string]Value of the Linked Data proof. or An object used to associate an enveloped verifiable credential with the verifiableCredential property in a verifiable presentation. It MUST be an object of the following form: @context [array]The JSON-LD context of the enveloped verifiable credential. Each item in the @context array MUST be a string.id [string]This MUST be a "data:" scheme URL [RFC2397] that expresses a secured verifiable credential using an enveloping security scheme. type [string]This MUST be EnvelopedVerifiableCredential. content-type: application/json 400 Bad Request 401 Not Authorized 404 Credential not found 410 Gone! There is no data here 418 I'm a teapot - MUST not be returned outside of pre-arranged scenarios between both parties Update Status POST /credentials/status - Updates the status of an issued credential The /credentials/status endpoint uses the following schema when receiving a POST: Property Description credentialId [string] Identifies the credential (the identifier does not have to appear in the VC itself). credentialStatus [object] Identifies the specific status list entry to update. It MUST be an object of the following form: id [string]type [string]statusPurpose [string]statusListIndex [string]statusListCredential [string] status [boolean] Specifies the new status. indexAllocator [string] For services to use which indexes are being used/assigned to VCs. The /credentials/status endpoint can result in any of these responses when receiving a POST: Response Body 200 Credential status successfully updated 400 Bad Request 404 Credential not found Delete a Specific Credential An issuer service or a holder service might store an issued verifiable credential for an extended period of time. When this is done, it can be useful to delete such a verifiable credential; for instance, an issuer might need to do so because of regulatory requirements such as the right to be forgotten. See Section B.3 Deletion for additional considerations related to the removal of verifiable credentials from systems. DELETE /credentials/{id} - Deletes a credential or verifiable credential by ID. To delete a credential that does not have credential.id set but has an associated credentialId value, pass credentialId instead. The /credentials/{id} endpoint can result in any of these responses when receiving a DELETE: Response Body 202 Credential deleted - this is a 202 by default as soft deletes and processing time are assumed 400 Bad Request 401 Not Authorized 404 Credential not found 410 Gone! There is no data here Verifying The following APIs are defined for verifying a Verifiable Credential: Endpoint Description POST /credentials/verify Verifies a verifiableCredential and returns a verificationResult in the response body. POST /presentations/verify Verifies a Presentation and all Verifiable Credentials it contains, returning detailed verification results. POST /challenges Passing an empty body to this endpoint creates and returns a challenge string in the response body. Verify Credential This endpoint is used to verify a verifiable credential. Note : Verify credential media types To verify credentials with a media type other than application/vc, such as application/mdoc, application/vc+sd-jwt, application/vcb;barcode-format=qr_code, or application/vcb;barcode-format=pdf417 — an EnvelopedVerifiableCredential can be provided in the request. POST /credentials/verify - Verifies a verifiableCredential and returns a verificationResult in the response body. The /credentials/verify endpoint uses one of the following schemas when receiving a POST: Property Description verifiableCredential [object] an object of the following form: @context [array]The JSON-LD context of the credential. Each item in the @context array MUST be a string.id [string]The ID of the credential. This property MAY be empty. The issuer SHOULD NOT auto-generate the id property if not provided, as a Verifiable Credential does not require the id property to be valid, and there are use cases for which the id property cannot be set. type [array]The JSON-LD type of the credential. Each item in the type array MUST be a string.issuer [object]Either a string or an object of the following form: id [string]The issuer id. issuanceDate [string]The issuanceDate expirationDate [string]The expirationDate credentialSubject [object]an objectproof [object]A Data Integrity Proof as defined by the W3C VC Data Integrity specification. It MUST be an object of the following form: type [string]Data Integrity Proof type. cryptosuite [string]The name of the cryptographic suite. created [string]Date the proof was created. nonce [string]A value chosen by the creator of a proof to randomize proof values for privacy purposes. verificationMethod [string]Verification Method used to verify proof. proofPurpose [string]The purpose of the proof to be used with verificationMethod. proofValue [string]Value of the Linked Data proof. options [object] Options for specifying how a credential is verified It MUST be an object of the following form: returnResults [boolean]Include results for each verification steps taken in the response, such as verifying individual proofs, statuses and schemas. returnProblemDetails [boolean]Include ProblemDetails errors and warnings in the response. returnCredential [boolean]Should the verified credential be returned in the response? If true, then the verified credential should be returned in the form in which it was verified. If false or not provided, then the verified credential should not be returned. Alternatively, the /credentials/verify endpoint can also use the following schema: Property Description verifiableCredential [object] An object used to associate an enveloped verifiable credential with the verifiableCredential property in a verifiable presentation. It MUST be an object of the following form: @context [array]The JSON-LD context of the enveloped verifiable credential. Each item in the @context array MUST be a string.id [string]This MUST be a "data:" scheme URL [RFC2397] that expresses a secured verifiable credential using an enveloping security scheme. type [string]This MUST be EnvelopedVerifiableCredential. options [object] Options for specifying how a credential is verified It MUST be an object of the following form: returnResults [boolean]Include results for each verification steps taken in the response, such as verifying individual proofs, statuses and schemas. returnProblemDetails [boolean]Include ProblemDetails errors and warnings in the response. returnCredential [boolean]Should the verified credential be returned in the response? If true, then the verified credential should be returned in the form in which it was verified. If false or not provided, then the verified credential should not be returned. The /credentials/verify endpoint can result in any of these responses when receiving a POST: Response Body 200 Verifiable Credential successfully verified! Object to report the result of a verification process on a VerifiableCredential. It MUST be an object of the following form: verified [boolean]Overall verification assertion of the VerifiableCredential. This is set to true if no errors were detected during the verification process; otherwise, false. See error handling section for more guidance around errors, warnings, and verification steps. credential [object]an objectproblemDetails [array]Array consisting of ProblemDetails objects. Each item in the problemDetails array MUST be an object of the following form: type [string]URL identifying the type of problem. title [string]Short but specific human-readable string for the problem. detail [string]Longer human-readable string for the problem. results [object]Verification results to be included as a more verbose output. Keys are mapped to properties from the Verifiable Credential Data Model. It MUST be an object of the following form: validFrom [object]Results of verifying the validFrom property, if present in the VerifiableCredential. It MUST be an object of the following form: verified [boolean]Verification result. input [string]The validFrom value. validUntil [object]Results of verifying the validUntil property, if present in the VerifiableCredential. It MUST be an object of the following form: verified [boolean]Verification result. input [string]The validUntil value. credentialSchema [array]Results from verifying the credentialSchema objects if any. Each item in the credentialSchema array MUST be Results from verifying a credentialSchema object. It MUST be an object of the following form: verified [boolean]Results of verifying the credentialSchema object. input [object]an objectcredentialStatus [array]Results from verifying the credentialStatus objects if any. Each item in the credentialStatus array MUST be Results of verifying a credentialStatus object. It MUST be an object of the following form: value [integer]The specific status value associated with the status entry. verified [boolean]Results of verifying the credentialStatus object. input [object]an objectproof [array]Results from verifying the proof objects if any. Each item in the proof array MUST be Results from verifying a proof object. It MUST be an object of the following form: verified [boolean]Results of verifying the proof object. input [object]an object content-type: application/json 400 invalid input! Verify Presentation This endpoint is used to verify a verifiable presentation and, by default, all verifiable credentials contained within it. The verification process includes: * Verifying the presentation's own proof (including domain and challenge validation) * Verifying each contained verifiable credential's proof, status, and validity period(s) * Checking that the holder in the presentation matches the verification method used in the presentation's proof Business rule validation (such as verifying that credential subjects match the presentation holder, or authorization policies about who can present which credentials) is outside the scope of this verification endpoint and should be performed by the calling application. POST /presentations/verify - Verifies a Presentation and all Verifiable Credentials it contains, returning detailed verification results. The /presentations/verify endpoint uses one of the following schemas when receiving a POST: Property Description verifiablePresentation [object] an object of the following form: @context [array]The JSON-LD context of the presentation. Each item in the @context array MUST be a string.id [string]The ID of the presentation. type [array]The JSON-LD type of the presentation. Each item in the type array MUST be a string.holder [object]an objectverifiableCredential [array]The Verifiable Credentials Each item in the verifiableCredential array MUST be an object of the following form: @context [array]The JSON-LD context of the credential. Each item in the @context array MUST be a string.id [string]The ID of the credential. This property MAY be empty. The issuer SHOULD NOT auto-generate the id property if not provided, as a Verifiable Credential does not require the id property to be valid, and there are use cases for which the id property cannot be set. type [array]The JSON-LD type of the credential. Each item in the type array MUST be a string.issuer [object]Either a string or an object of the following form: id [string]The issuer id. issuanceDate [string]The issuanceDate expirationDate [string]The expirationDate credentialSubject [object]an objectproof [object]A Data Integrity Proof as defined by the W3C VC Data Integrity specification. It MUST be an object of the following form: type [string]Data Integrity Proof type. cryptosuite [string]The name of the cryptographic suite. created [string]Date the proof was created. nonce [string]A value chosen by the creator of a proof to randomize proof values for privacy purposes. verificationMethod [string]Verification Method used to verify proof. proofPurpose [string]The purpose of the proof to be used with verificationMethod. proofValue [string]Value of the Linked Data proof. proof [object]A Data Integrity Proof that includes a challenge and a domain as defined by the W3C VC Data Integrity specification. It MUST be an object of the following form: type [string]Data Integrity Proof type. cryptosuite [string]The name of the cryptographic suite. created [string]Date the proof was created. challenge [string]A value chosen by the verifier to mitigate authentication proof replay attacks. domain [string]The domain of the proof to restrict its use to a particular target. nonce [string]A value chosen by the creator of a proof to randomize proof values for privacy purposes. verificationMethod [string]Verification Method used to verify proof. proofPurpose [string]The purpose of the proof to be used with verificationMethod. proofValue [string]Value of the Linked Data proof. options [object] Options for specifying how a presentation is verified. Implementations MAY extend this object with additional properties to control verification behavior. Common extensions may include options to disable verification of contained credentials (e.g., for debugging or when only presentation-level verification is needed); fine-grained controls for verification of credential aspects such as status checks, validity period validation, proof verification, and schema validation; and selective verification controls for specific credentials within the presentation. The API is compositional when credential verification is disabled or limited; indvidual credentials can be verified separately using the /credentials/verify endpoint. It MUST be an object of the following form: challenge [string]A challenge provided by the requesting party of the proof; for example, 6e62f66e-67de-11eb-b490-ef3eeefa55f2. domain [string]The intended domain of validity for the proof; for example, website.example. returnPresentation [boolean]Whether or not to return the verified presentation. If true, then the verified presentation MUST be returned. If false or not provided, then the verified presentation MUST NOT be returned. Alternatively, the /presentations/verify endpoint can also use the following schema: Property Description presentation [object] A JSON-LD Verifiable Presentation without a proof. It MUST be an object of the following form: @context [array]The JSON-LD context of the presentation. Each item in the @context array MUST be a string.id [string]The ID of the presentation. type [array]The JSON-LD type of the presentation. Each item in the type array MUST be a string.holder [object]an objectverifiableCredential [array]The Verifiable Credentials Each item in the verifiableCredential array MUST be an object of the following form: @context [array]The JSON-LD context of the credential. Each item in the @context array MUST be a string.id [string]The ID of the credential. This property MAY be empty. The issuer SHOULD NOT auto-generate the id property if not provided, as a Verifiable Credential does not require the id property to be valid, and there are use cases for which the id property cannot be set. type [array]The JSON-LD type of the credential. Each item in the type array MUST be a string.issuer [object]Either a string or an object of the following form: id [string]The issuer id. issuanceDate [string]The issuanceDate expirationDate [string]The expirationDate credentialSubject [object]an objectproof [object]A Data Integrity Proof as defined by the W3C VC Data Integrity specification. It MUST be an object of the following form: type [string]Data Integrity Proof type. cryptosuite [string]The name of the cryptographic suite. created [string]Date the proof was created. nonce [string]A value chosen by the creator of a proof to randomize proof values for privacy purposes. verificationMethod [string]Verification Method used to verify proof. proofPurpose [string]The purpose of the proof to be used with verificationMethod. proofValue [string]Value of the Linked Data proof. Property Description verifiablePresentation [object] An object used to express an enveloped verifiable presentation. It MUST be an object of the following form: @context [array]The JSON-LD context of the enveloped verifiable presentation. Each item in the @context array MUST be a string.id [string]This MUST be a "data:" scheme URL [RFC2397] that expresses a secured verifiable presentation using an enveloping security scheme. type [string]This MUST be EnvelopedVerifiablePresentation. options [object] Options for specifying how a presentation is verified. Implementations MAY extend this object with additional properties to control verification behavior. Common extensions may include options to disable verification of contained credentials (e.g., for debugging or when only presentation-level verification is needed); fine-grained controls for verification of credential aspects such as status checks, validity period validation, proof verification, and schema validation; and selective verification controls for specific credentials within the presentation. The API is compositional when credential verification is disabled or limited; indvidual credentials can be verified separately using the /credentials/verify endpoint. It MUST be an object of the following form: challenge [string]A challenge provided by the requesting party of the proof; for example, 6e62f66e-67de-11eb-b490-ef3eeefa55f2. domain [string]The intended domain of validity for the proof; for example, website.example. returnPresentation [boolean]Whether or not to return the verified presentation. If true, then the verified presentation MUST be returned. If false or not provided, then the verified presentation MUST NOT be returned. The /presentations/verify endpoint can result in any of these responses when receiving a POST: Response Body 200 Verification process completed successfully. The response body contains detailed results indicating whether the presentation and its contained credentials passed or failed verification. A <code>200</code> status indicates the verification process itself succeeded, regardless of whether the presentation and/or credentials were determined to be valid or invalid. Object to report the result of a verification process on a VerifiablePresentation. It MUST be an object of the following form: verified [boolean]Overall verification assertion of the VerifiablePresentation. This is set to true if the VerifiablePresentation and all checked VerifiableCredentials passed verification; otherwise, false. See error handling section for more guidance around errors and warnings, and validation and verification steps. verifiablePresentation [object]an objectproblemDetails [array]Array consisting of ProblemDetails objects for overall presentation-level issues. Each item in the problemDetails array MUST be an object of the following form: type [string]URL identifying the type of problem. title [string]Short but specific human-readable string for the problem. detail [string]Longer human-readable string for the problem. results [object]Detailed verification results for both VerifiablePresentation and all VerifiableCredentials contained within it, by default. Keys are mapped to properties from the Verifiable Credential Data Model which are subject to validations. It MUST be an object of the following form: presentation [object]Verification results specific to the VerifiablePresentation itself (not its contained VerifiableCredentials). It MUST be an object of the following form: challenge [object]If provided in the verification options, the result of verifying the security challenge across all proofs provided. It MUST be an object of the following form: verified [boolean]Result of verifying the security challenge across all proofs provided. input [string]The challenge input string. domain [object]If provided in the verification options, the result of verifying the security domain across all proofs provided. It MUST be an object of the following form: verified [boolean]Result of verifying the security domain across all proofs provided. input [string]The security domain input string. holder [object]Result from verifying the holder, if any. It MUST be an object of the following form: verified [boolean]Result of verifying the holder. input [string]The holder input string. proof [array]Results from verifying the proof objects if any. Each item in the proof array MUST be Results from verifying a proof object. It MUST be an object of the following form: verified [boolean]Results of verifying the proof object. input [object]an objectproblemDetails [array]Issues sepecific to this proof. Each item in the problemDetails array MUST be an object of the following form: type [string]URL identifying the type of problem. title [string]Short but specific human-readable string for the problem. detail [string]Longer human-readable string for the problem. credentials [array]Detailed verification results for each VerifiableCredential in the VerifiablePresentation. Each item in the credentials array MUST be Object to report the result of a verification process on a VerifiableCredential. It MUST be an object of the following form: verified [boolean]Overall verification assertion of the VerifiableCredential. This is set to true if no errors were detected during the verification process; otherwise, false. See error handling section for more guidance around errors, warnings, and verification steps. credential [object]an objectproblemDetails [array]Array consisting of ProblemDetails objects. Each item in the problemDetails array MUST be an object of the following form: type [string]URL identifying the type of problem. title [string]Short but specific human-readable string for the problem. detail [string]Longer human-readable string for the problem. results [object]Verification results to be included as a more verbose output. Keys are mapped to properties from the Verifiable Credential Data Model. It MUST be an object of the following form: validFrom [object]Results of verifying the validFrom property, if present in the VerifiableCredential. It MUST be an object of the following form: verified [boolean]Verification result. input [string]The validFrom value. validUntil [object]Results of verifying the validUntil property, if present in the VerifiableCredential. It MUST be an object of the following form: verified [boolean]Verification result. input [string]The validUntil value. credentialSchema [array]Results from verifying the credentialSchema objects if any. Each item in the credentialSchema array MUST be Results from verifying a credentialSchema object. It MUST be an object of the following form: verified [boolean]Results of verifying the credentialSchema object. input [object]an objectcredentialStatus [array]Results from verifying the credentialStatus objects if any. Each item in the credentialStatus array MUST be Results of verifying a credentialStatus object. It MUST be an object of the following form: value [integer]The specific status value associated with the status entry. verified [boolean]Results of verifying the credentialStatus object. input [object]an objectproof [array]Results from verifying the proof objects if any. Each item in the proof array MUST be Results from verifying a proof object. It MUST be an object of the following form: verified [boolean]Results of verifying the proof object. input [object]an object content-type: application/json 400 Invalid or malformed input that prevented the verification process from being performed. This indicates issues with the request format, structure, or parameters, rather than verification failures. 413 Payload too large 429 Request rate limit exceeded. Create Challenge POST /challenges - Passing an empty body to this endpoint creates and returns a challenge string in the response body. The /challenges endpoint can result in any of these responses when receiving a POST: Response Body 200 Challenge created Object containg a challenge It MUST be an object of the following form: challenge [string]The challenge value content-type: application/json 400 Invalid or malformed input The instance should create a challenge for use during verification, and track the number of times the challenge has been passed to verification endpoints as options.challenge. Requesting a Presentation 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. Verifiable Presentation Request A verifiable presentation request is a request a verifier makes to a holder for a presentation. To make a request for one or more credentials wrapped in a verifiable presentation, a verifier constructs a JSON request describing one or more credentials that it wishes to receive from the holder. The general format for a request looks like the following: Example 1 : The general form of a verifiable presentation request { // 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" } The query property serves as the main extension point mechanism for requests for data in the presentation. While this document defines a common query mechanism (see Section Query By Example), all query objects are of the following form: query A REQUIRED property that specifies the information requested by the verifier. The value MUST be one or more maps where each map MUST define a type property with an associated string value. domain An OPTIONAL string that a verifier provides to a holder during a presentation request. The holder checks to ensure that the data is associated with the domain, such as a website domain, that they are interacting with, and if it is, includes the data in a verifiable presentation. A domain is used to ensure that the holder limits their verifiable presentation to a specific verifier, protecting the verifier against replay attacks. challenge An OPTIONAL, unique string that is provided by a verifier to a holder during a specific presentation request. The holder includes this data in a verifiable presentation to the verifier, protecting the verifier against replay attacks. Query By Example The "query by example" credential query format is designed to enable developers to easily request the claims that they need from one or more verifiable credentials, to enable a particular business process. The query can also specify other information, such as one or more issuers that are trusted by the verifier. Example 2 : A Query By Example query { "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" } DID Authentication This section defines how a verifier can request that a holder perform Decentralized Identifier-based Authentication [DID-CORE]. In its simplest form, the authentication protocol is comprised of a challenge by the verifier and a response by a holder: Example 3 : A DID Authentication request { "query": [{ "type": "DIDAuthentication", "acceptedMethods": [{"method": "example"}] }], "challenge": "99612b24-63d9-11ea-b99f-4f66f3e4f81a", "domain": "example.com" } The DID Authentication request above specifies that the verifier would like the holder to demonstrate control over a DID by generating a digital signature over the provided challenge. The holder might respond by providing the following response: Example 4 : A DID Authentication response { "@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" } } Issue 2 The DID Authentication examples shown in this document use a new proof type called DataIntegrityProof which is currently under development in the W3C Verifiable Credentials Working Group. The DID Authentication Query Format The DID Authentication query format enables a verifier to request that a holder authenticate in specific ways. A DID Authentication query MUST be of the following form: Property Description type A REQUIRED string value that MUST be set to DIDAuthentication. An optional array of objects expressing that the verifier would accept any DID Method listed. Each object in the array MUST contain a property called method with a value that is a DID Method name, and MAY contain other properties that are specific to the DID Method. Valid example values include: acceptedMethods * [{"method": "key"}] * [{"method": "key"}, {"method": "web"}] An optional array of objects that conveys the cryptography suites among which the holder MUST choose when generating a cryptographic proof to be submitted to this verifier. Each object in the array MUST contain a property called cryptosuite with a value that is a cryptosuite name, and MAY contain other properties that are specific to the cryptosuite. Valid example values include: acceptedCryptosuites * [{"cryptosuite": "eddsa-rdfc-2022"}] * [{"cryptosuite": "ecdsa-rdfc-2019"}, {"cryptosuite": "bbs-2023"}] The following example demonstrates that the verifier would like the holder to use the DID Web method and a data integrity ECDSA cryptography suite to authenticate over the established communication channel, such as the Credential Handler API (CHAPI): Example 5 : A DID Authentication request using did:web and ecdsa-rdfc-2019 { "query": [{ "type": "DIDAuthentication", "acceptedMethods": [{"method": "key"}], "acceptedCryptosuites": [{"cryptosuite": "ecdsa-rdfc-2019"}] }], "challenge": "99612b24-63d9-11ea-b99f-4f66f3e4f81a", "domain": "example.com" } In the next example, the verifier would like the holder to use either the DID Key or DID Web method, with the standard EdDSA data integrity cryptography suite; optionally include a cryptographic proof that they are capable of performing a data integrity BBS proof; and authenticate over a different communication channel, in this case using a Verifiable Credential API HTTP endpoint. Example 6 : A complex DID Authentication request { "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" } The DID Authentication Response Format The DID Authentication response format enables a holder to provide the information requested by the verifier. A DID Authentication response MUST be a verifiable presentation of the following form: Property Description type A REQUIRED string value that MUST be set to VerifiablePresentation. holder A REQUIRED string value that MUST be set to a specific DID that is of the type that was requested in the DID Authentication query. proof A REQUIRED value that MUST be one or more specific digital proof types that were requested in the DID Authentication query. Each proof object MUST include the domain and challenge values that were provided in the DID Authentication query. Holder implementations MUST ensure that the domain specified by the verifier matches the domain used for the current channel of communication. It is vital that a holder implementation check the domain provided by the verifier against the domain used for the current channel of communication. If a holder fails to do so, a dishonest verifier could then replay the message to a domain that is not their own. For example, a dishonest verifier operating from the evil.example domain could retrieve a challenge from your bank, specify a domain value of yourbank.example, and then replay your response to your bank to get access to your financial accounts. This attack is mitigated as long as implementations ensure that the appropriate domain is used when generating the verifiable presentation. The example below demonstrates a simple DID Authentication response. Example 7 : A DID Authentication response using did:key { "@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" } } Authorization Capability Request Issue 3 Authorization Capability queries and responses might not be standardized at this time. This example is provided to demonstrate that verifiable credentials and mDLs/mdocs are not the only type of credential that can be queried. This query type would be included in a request to ask for Authorization Capabilities or "zcaps" in the Verifiable Presentation. Example 8 : An Authorization Capability Request query { "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" }] } Logical Operations in Queries In Verifiable Presentation Requests, the structuring and retrieval of information rely on the use of logical operations. "AND" and "OR" operations play crucial roles in defining the path to desired data. Top-Level Queries ("AND" Operation) At the top-most level of the request structure, different types of queries are expected to be processed as "AND" operations if each one's group property is set to the same value. In this example, there are two queries with the group flag set to certification. This results in an "AND" operation, indicating that both of these conditions need to be met in order to fulfill the request. Example 9 : Multiple credentials requested at once using top-level queries { "query": [{ "type": "QueryByExample", "group": "certification", // query details ... }, // "AND" { "type": "DigitalCredentialQueryLanguage", "group": "certification", // query details ... }] } Nested Queries ("OR" Operation) Within a specific query type, an "OR" operation can be applied, by either not specifying the group or providing group values that are different from one another. Example 10 : Queries for alternate credentials where any match will succeed { "query": [{ "type": "QueryByExample", "group": "college-degree", // query details ... }, // "OR" { "type": "DigitalCredentialQueryLanguage", "group": "job-experience", // query details ... }] } Presenting The following APIs are defined for presenting a Verifiable Credential: Endpoint Description POST /credentials/derive Derives a credential and returns it in the response body. GET /presentations Gets list of presentations or verifiable presentations POST /presentations Creates a presentation and returns it in the response body. GET /presentations Gets list of presentations or verifiable presentations POST /presentations Creates a presentation and returns it in the response body. GET /presentations/{id} Gets a presentation or verifiable presentation by ID DELETE /presentations/{id} Deletes a presentation or verifiable presentation by ID POST /exchanges/ Error: API Endpoint not defined - /exchanges/ POST /exchanges/{exchange-id} Initiates an exchange of information. 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. Derive Credential POST /credentials/derive - Derives a credential and returns it in the response body. The /credentials/derive endpoint uses the following schema when receiving a POST: Property Description verifiableCredential [object] an object of the following form: @context [array]The JSON-LD context of the credential. Each item in the @context array MUST be a string.id [string]The ID of the credential. This property MAY be empty. The issuer SHOULD NOT auto-generate the id property if not provided, as a Verifiable Credential does not require the id property to be valid, and there are use cases for which the id property cannot be set. type [array]The JSON-LD type of the credential. Each item in the type array MUST be a string.issuer [object]Either a string or an object of the following form: id [string]The issuer id. issuanceDate [string]The issuanceDate expirationDate [string]The expirationDate credentialSubject [object]an objectproof [object]A Data Integrity Proof as defined by the W3C VC Data Integrity specification. It MUST be an object of the following form: type [string]Data Integrity Proof type. cryptosuite [string]The name of the cryptographic suite. created [string]Date the proof was created. nonce [string]A value chosen by the creator of a proof to randomize proof values for privacy purposes. verificationMethod [string]Verification Method used to verify proof. proofPurpose [string]The purpose of the proof to be used with verificationMethod. proofValue [string]Value of the Linked Data proof. options [object] Options for specifying how the derived credential is created. It MUST be an object of the following form: selectivePointers [array]An array of JSON pointers specifying the selectively disclosed information. Each item in the selectivePointers array MUST be a string. The /credentials/derive endpoint can result in any of these responses when receiving a POST: Response Body 201 Credential derived successfully. an object of the following form: @context [array]The JSON-LD context of the credential. Each item in the @context array MUST be a string.id [string]The ID of the credential. This property MAY be empty. The issuer SHOULD NOT auto-generate the id property if not provided, as a Verifiable Credential does not require the id property to be valid, and there are use cases for which the id property cannot be set. type [array]The JSON-LD type of the credential. Each item in the type array MUST be a string.issuer [object]Either a string or an object of the following form: id [string]The issuer id. issuanceDate [string]The issuanceDate expirationDate [string]The expirationDate credentialSubject [object]an objectproof [object]A Data Integrity Proof as defined by the W3C VC Data Integrity specification. It MUST be an object of the following form: type [string]Data Integrity Proof type. cryptosuite [string]The name of the cryptographic suite. created [string]Date the proof was created. nonce [string]A value chosen by the creator of a proof to randomize proof values for privacy purposes. verificationMethod [string]Verification Method used to verify proof. proofPurpose [string]The purpose of the proof to be used with verificationMethod. proofValue [string]Value of the Linked Data proof. content-type: application/json 400 Invalid Request Create Presentation Note : Presentation media types An EnvelopedVerifiablePresentation can be returned in the response in order to create presentations with a media type other than application/vp, such as application/vp+jwt. POST /presentations - Creates a presentation and returns it in the response body. The /presentations endpoint uses the following schema when receiving a POST: Property Description presentation [object] A JSON-LD Verifiable Presentation without a proof. It MUST be an object of the following form: @context [array]The JSON-LD context of the presentation. Each item in the @context array MUST be a string.id [string]The ID of the presentation. type [array]The JSON-LD type of the presentation. Each item in the type array MUST be a string.holder [object]an objectverifiableCredential [array]The Verifiable Credentials Each item in the verifiableCredential array MUST be an object of the following form: @context [array]The JSON-LD context of the credential. Each item in the @context array MUST be a string.id [string]The ID of the credential. This property MAY be empty. The issuer SHOULD NOT auto-generate the id property if not provided, as a Verifiable Credential does not require the id property to be valid, and there are use cases for which the id property cannot be set. type [array]The JSON-LD type of the credential. Each item in the type array MUST be a string.issuer [object]Either a string or an object of the following form: id [string]The issuer id. issuanceDate [string]The issuanceDate expirationDate [string]The expirationDate credentialSubject [object]an objectproof [object]A Data Integrity Proof as defined by the W3C VC Data Integrity specification. It MUST be an object of the following form: type [string]Data Integrity Proof type. cryptosuite [string]The name of the cryptographic suite. created [string]Date the proof was created. nonce [string]A value chosen by the creator of a proof to randomize proof values for privacy purposes. verificationMethod [string]Verification Method used to verify proof. proofPurpose [string]The purpose of the proof to be used with verificationMethod. proofValue [string]Value of the Linked Data proof. options [object] Options for specifying how the DataIntegrityProof is created. It MUST be an object of the following form: type [string]The type of the proof. Default 'DataIntegrityProof'. cryptosuite [string]The cryptosuite of the proof. verificationMethod [string]The URI of the verificationMethod used for the proof. If omitted, a default verification method will be used. proofPurpose [string]The purpose of the proof. Default 'assertionMethod'. created [string]The date and time of the proof (with a maximum accuracy in seconds). Default current system time. challenge [string]A challenge provided by the requesting party of the proof. For example 6e62f66e-67de-11eb-b490-ef3eeefa55f2 domain [string]The intended domain of validity for the proof. For example website.example The /presentations endpoint can result in any of these responses when receiving a POST: Response Body 201 Presentation successfully created! an object of the following form: verifiablePresentation [object]Either an object of the following form: @context [array]The JSON-LD context of the presentation. Each item in the @context array MUST be a string.id [string]The ID of the presentation. type [array]The JSON-LD type of the presentation. Each item in the type array MUST be a string.holder [object]an objectverifiableCredential [array]The Verifiable Credentials Each item in the verifiableCredential array MUST be an object of the following form: @context [array]The JSON-LD context of the credential. Each item in the @context array MUST be a string.id [string]The ID of the credential. This property MAY be empty. The issuer SHOULD NOT auto-generate the id property if not provided, as a Verifiable Credential does not require the id property to be valid, and there are use cases for which the id property cannot be set. type [array]The JSON-LD type of the credential. Each item in the type array MUST be a string.issuer [object]Either a string or an object of the following form: id [string]The issuer id. issuanceDate [string]The issuanceDate expirationDate [string]The expirationDate credentialSubject [object]an objectproof [object]A Data Integrity Proof as defined by the W3C VC Data Integrity specification. It MUST be an object of the following form: type [string]Data Integrity Proof type. cryptosuite [string]The name of the cryptographic suite. created [string]Date the proof was created. nonce [string]A value chosen by the creator of a proof to randomize proof values for privacy purposes. verificationMethod [string]Verification Method used to verify proof. proofPurpose [string]The purpose of the proof to be used with verificationMethod. proofValue [string]Value of the Linked Data proof. proof [object]A Data Integrity Proof that includes a challenge and a domain as defined by the W3C VC Data Integrity specification. It MUST be an object of the following form: type [string]Data Integrity Proof type. cryptosuite [string]The name of the cryptographic suite. created [string]Date the proof was created. challenge [string]A value chosen by the verifier to mitigate authentication proof replay attacks. domain [string]The domain of the proof to restrict its use to a particular target. nonce [string]A value chosen by the creator of a proof to randomize proof values for privacy purposes. verificationMethod [string]Verification Method used to verify proof. proofPurpose [string]The purpose of the proof to be used with verificationMethod. proofValue [string]Value of the Linked Data proof. or An object used to express an enveloped verifiable presentation. It MUST be an object of the following form: @context [array]The JSON-LD context of the enveloped verifiable presentation. Each item in the @context array MUST be a string.id [string]This MUST be a "data:" scheme URL [RFC2397] that expresses a secured verifiable presentation using an enveloping security scheme. type [string]This MUST be EnvelopedVerifiablePresentation. content-type: application/json 400 invalid input! Exchange Discovery Discovery is an optional call for the holder coordinator to ensure the holder coordinator can support the exchange protocol requirements before calling the endpoint. Coordinators SHOULD support the exchange discovery endpoint. POST /exchanges/ - Error: API Endpoint not defined - /exchanges/ The /exchanges/ endpoint can result in any of these responses when receiving a POST: Response Body Get Presentations GET /presentations - Gets list of presentations or verifiable presentations The /presentations endpoint can result in any of these responses when receiving a GET: Response Body 200 Presentations retrieved Each item in the array MUST be A JSON-LD Verifiable Presentation without a proof. It MUST be an object of the following form: @context [array]The JSON-LD context of the presentation. Each item in the @context array MUST be a string.id [string]The ID of the presentation. type [array]The JSON-LD type of the presentation. Each item in the type array MUST be a string.holder [object]an objectverifiableCredential [array]The Verifiable Credentials Each item in the verifiableCredential array MUST be an object of the following form: @context [array]The JSON-LD context of the credential. Each item in the @context array MUST be a string.id [string]The ID of the credential. This property MAY be empty. The issuer SHOULD NOT auto-generate the id property if not provided, as a Verifiable Credential does not require the id property to be valid, and there are use cases for which the id property cannot be set. type [array]The JSON-LD type of the credential. Each item in the type array MUST be a string.issuer [object]Either a string or an object of the following form: id [string]The issuer id. issuanceDate [string]The issuanceDate expirationDate [string]The expirationDate credentialSubject [object]an objectproof [object]A Data Integrity Proof as defined by the W3C VC Data Integrity specification. It MUST be an object of the following form: type [string]Data Integrity Proof type. cryptosuite [string]The name of the cryptographic suite. created [string]Date the proof was created. nonce [string]A value chosen by the creator of a proof to randomize proof values for privacy purposes. verificationMethod [string]Verification Method used to verify proof. proofPurpose [string]The purpose of the proof to be used with verificationMethod. proofValue [string]Value of the Linked Data proof. or an object of the following form: @context [array]The JSON-LD context of the presentation. Each item in the @context array MUST be a string.id [string]The ID of the presentation. type [array]The JSON-LD type of the presentation. Each item in the type array MUST be a string.holder [object]an objectverifiableCredential [array]The Verifiable Credentials Each item in the verifiableCredential array MUST be an object of the following form: @context [array]The JSON-LD context of the credential. Each item in the @context array MUST be a string.id [string]The ID of the credential. This property MAY be empty. The issuer SHOULD NOT auto-generate the id property if not provided, as a Verifiable Credential does not require the id property to be valid, and there are use cases for which the id property cannot be set. type [array]The JSON-LD type of the credential. Each item in the type array MUST be a string.issuer [object]Either a string or an object of the following form: id [string]The issuer id. issuanceDate [string]The issuanceDate expirationDate [string]The expirationDate credentialSubject [object]an objectproof [object]A Data Integrity Proof as defined by the W3C VC Data Integrity specification. It MUST be an object of the following form: type [string]Data Integrity Proof type. cryptosuite [string]The name of the cryptographic suite. created [string]Date the proof was created. nonce [string]A value chosen by the creator of a proof to randomize proof values for privacy purposes. verificationMethod [string]Verification Method used to verify proof. proofPurpose [string]The purpose of the proof to be used with verificationMethod. proofValue [string]Value of the Linked Data proof. proof [object]A Data Integrity Proof that includes a challenge and a domain as defined by the W3C VC Data Integrity specification. It MUST be an object of the following form: type [string]Data Integrity Proof type. cryptosuite [string]The name of the cryptographic suite. created [string]Date the proof was created. challenge [string]A value chosen by the verifier to mitigate authentication proof replay attacks. domain [string]The domain of the proof to restrict its use to a particular target. nonce [string]A value chosen by the creator of a proof to randomize proof values for privacy purposes. verificationMethod [string]Verification Method used to verify proof. proofPurpose [string]The purpose of the proof to be used with verificationMethod. proofValue [string]Value of the Linked Data proof. content-type: application/json 400 Bad Request 401 Not Authorized 410 Gone! There is no data here Get a Specific Presentation GET /presentations/{id} - Gets a presentation or verifiable presentation by ID The /presentations/{id} endpoint can result in any of these responses when receiving a GET: Response Body 200 Credential retrieved A JSON-LD Verifiable Presentation without a proof. It MUST be an object of the following form: @context [array]The JSON-LD context of the presentation. Each item in the @context array MUST be a string.id [string]The ID of the presentation. type [array]The JSON-LD type of the presentation. Each item in the type array MUST be a string.holder [object]an objectverifiableCredential [array]The Verifiable Credentials Each item in the verifiableCredential array MUST be an object of the following form: @context [array]The JSON-LD context of the credential. Each item in the @context array MUST be a string.id [string]The ID of the credential. This property MAY be empty. The issuer SHOULD NOT auto-generate the id property if not provided, as a Verifiable Credential does not require the id property to be valid, and there are use cases for which the id property cannot be set. type [array]The JSON-LD type of the credential. Each item in the type array MUST be a string.issuer [object]Either a string or an object of the following form: id [string]The issuer id. issuanceDate [string]The issuanceDate expirationDate [string]The expirationDate credentialSubject [object]an objectproof [object]A Data Integrity Proof as defined by the W3C VC Data Integrity specification. It MUST be an object of the following form: type [string]Data Integrity Proof type. cryptosuite [string]The name of the cryptographic suite. created [string]Date the proof was created. nonce [string]A value chosen by the creator of a proof to randomize proof values for privacy purposes. verificationMethod [string]Verification Method used to verify proof. proofPurpose [string]The purpose of the proof to be used with verificationMethod. proofValue [string]Value of the Linked Data proof. or an object of the following form: @context [array]The JSON-LD context of the presentation. Each item in the @context array MUST be a string.id [string]The ID of the presentation. type [array]The JSON-LD type of the presentation. Each item in the type array MUST be a string.holder [object]an objectverifiableCredential [array]The Verifiable Credentials Each item in the verifiableCredential array MUST be an object of the following form: @context [array]The JSON-LD context of the credential. Each item in the @context array MUST be a string.id [string]The ID of the credential. This property MAY be empty. The issuer SHOULD NOT auto-generate the id property if not provided, as a Verifiable Credential does not require the id property to be valid, and there are use cases for which the id property cannot be set. type [array]The JSON-LD type of the credential. Each item in the type array MUST be a string.issuer [object]Either a string or an object of the following form: id [string]The issuer id. issuanceDate [string]The issuanceDate expirationDate [string]The expirationDate credentialSubject [object]an objectproof [object]A Data Integrity Proof as defined by the W3C VC Data Integrity specification. It MUST be an object of the following form: type [string]Data Integrity Proof type. cryptosuite [string]The name of the cryptographic suite. created [string]Date the proof was created. nonce [string]A value chosen by the creator of a proof to randomize proof values for privacy purposes. verificationMethod [string]Verification Method used to verify proof. proofPurpose [string]The purpose of the proof to be used with verificationMethod. proofValue [string]Value of the Linked Data proof. proof [object]A Data Integrity Proof that includes a challenge and a domain as defined by the W3C VC Data Integrity specification. It MUST be an object of the following form: type [string]Data Integrity Proof type. cryptosuite [string]The name of the cryptographic suite. created [string]Date the proof was created. challenge [string]A value chosen by the verifier to mitigate authentication proof replay attacks. domain [string]The domain of the proof to restrict its use to a particular target. nonce [string]A value chosen by the creator of a proof to randomize proof values for privacy purposes. verificationMethod [string]Verification Method used to verify proof. proofPurpose [string]The purpose of the proof to be used with verificationMethod. proofValue [string]Value of the Linked Data proof. content-type: application/json 400 Bad Request 401 Not Authorized 404 Presentation not found 410 Gone! There is no data here Workflows and Exchanges 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. While there is no technical limitation on the number of steps in a workflow, implementers might want to use 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. These examples will be added later. 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: Endpoint Description POST /workflows Creates a new workflow and returns location of workflow metadata in a response header. GET /workflows/{localWorkflowId} Gets the configuration of an existing workflow and returns it in the response body. POST /workflows/{localWorkflowId}/exchanges Creates a new exchange and returns location of exchange metadata in a response header. GET /workflows/{localWorkflowId}/exchanges/{localExchangeId} Gets the state of an existing exchange and returns it in the response body. POST /workflows/{localWorkflowId}/exchanges/{localExchangeId} Participate in an exchange. Posting an empty body will start the exchange or return what the exchange is expecting to complete the next step. Posting a Verifiable Presentation Request will result in either a 4xx error or one of the following - a Verifiable Presentation or Verifiable Presentation Request that conforms to the client's request. If a Verifiable Presentation is sent, an additional Verifiable Presentation Request may also be sent to continue the exchange. 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. Create Workflow POST /workflows - Creates a new workflow and returns location of workflow metadata in a response header. The /workflows endpoint uses the following schema when receiving a POST: Property Description id [string] The ID that will be used for the created workflow. Passing an ID is OPTIONAL. initialStep [string] The step from the above set that the exchange starts on. Passing intialStep is REQUIRED. controller [string] An OPTIONAL property that specifies the root controller of the instance, which can be used by systems supporting authorization mechanisms like Authorization Capabilities (ZCAPs), which rely on object capabilities. This value can be used in conjunction with the authorization property to simultaneously allow other authorization mechanisms. authorization [object] An OPTIONAL property that specifies authorization scheme information for the endpoint, such as an OAuth2 configuration. It MUST be an object of the following form: oauth2 [object]OAuth2 configuration. It MUST be an object of the following form: issuerConfigUrl [string]OAuth2 issuer config URL. credentialTemplates [array] An array where each item MUST be an object of the following form: type [string]The type of template. template [string]The template itself. steps [object] One or more steps required to complete an exchange on the workflow. Passing the steps object is REQUIRED. The keys are one or more step names, where each STEP_NAME is replaced by the name of a step (such as request-employee-id), and the values are step configurations. It MUST be an object of the following form: STEP_NAME [object]Either Step data to be included if a template is not used. It MUST be an object of the following form: createChallenge [boolean]An optional step directive that tells the exchange to handle challenge management via a VC API verifier service it has a zcap for. verifiablePresentationRequest [object]A Verifiable Presentation Request. It MUST be an object of the following form: query [array]A set of one or more queries sent by the requester. Each item in the query array MUST be an object of the following form: type [array]The type of the query. Each item in the type array MUST be a string.challenge [string]A challenge, intended to prevent replay attacks, provided by the requester that is typically expected to be included in the Verifiable Presentation response. domain [string]A domain, intended to prevent replay attacks, provided by the requester that is typically expected to be included in the Verifiable Presentation response. interact [array]A list of interaction mechanisms that are supported by the server. Each item in the interact array MUST be an object of the following form: service [object]A service that is supported by the server that is capable of receiving a response to the Verifiable Presentation Request. It MUST be an object of the following form: type [array]The type of the service. Each item in the type array MUST be a string.serviceEndpoint [string]A URL that can be utilized for interacting with the service for the purposes of responding to the Verifiable Presentation Request. presentationSchemaEither A JSON Schema describing the validation to be performed on the presentation. It MUST be an object of the following form: type [string]The value MUST be JsonSchema. jsonSchema [object]an object or An alternate presentation schema format to use when validating a presentation in the current step. Additional properties are expected for a specific presentation schema type, but are beyond the scope of this specification. It MUST be an object of the following form: type [string]The type of presentation schema mechanism to use when validating the presentation. verifyPresentationResponseSchemaEither A JSON Schema describing the validation to be performed on the result of verifying the presentation. It MUST be an object of the following form: type [string]The value MUST be JsonSchema. jsonSchema [object]an object or An alternate presentation schema format to use on the result of verifying a presentation in the current step. Additional properties are expected for a specific presentation schema type, but are beyond the scope of this specification. It MUST be an object of the following form: type [string]The type of presentation schema mechanism to use when validating the result of verifying the presentation. nextStep [string]The name of the next step in the sequence. Passing nextStep is OPTIONAL. This field MUST NOT be present on the final step configuration. openId [object]Optional information to trigger OID4VP It MUST be an object of the following form: createAuthorizationRequest [string]If present, identifies the name of the template variable (in variables for an exchange) that the auto-generated OpenID for Verifiable Presentations Authorization Request will be stored in for subsequent use in the exchange. Either this or authorizationRequest MUST be present, but not both. The value of the named variable can be lazily generated when the Authorization Request is required, i.e., after the client of the exchange chooses to use the OID4VP protocol. This feature allows the Authorization Request to be generated by reusing values, e.g., a Verifiable Presentation Request, that only need to be specified once across multiple protocol offerings. authorizationRequest [object]an object or an object of the following form: stepTemplate [object]A template for a workflow step. Either this must be present or the other step data must be present, but not both sets. It MUST be an object of the following form: type [string]The type of template. template [string]The step template. The /workflows endpoint can result in any of these responses when receiving a POST: Response Body 201 Workflow successfully created (with data) 204 Workflow successfully created (without data) 400 Invalid input 401 Not Authorized 500 Internal Error For the openId options above, specifically the values createAuthorizationRequest and authorizationRequest, the example below is provided to help developers understand what an OID4VP Authorization Request looks like: Example 11 : An OID4VP Authorization Request { "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" } Get Workflow Configuration GET /workflows/{localWorkflowId} - Gets the configuration of an existing workflow and returns it in the response body. The /workflows/{localWorkflowId} endpoint can result in any of these responses when receiving a GET: Response Body 200 Workflow configuration retrieved! Object containing information about a workflow. It MUST be an object of the following form: id [string]The ID that will be used for the created workflow. Passing an ID is OPTIONAL. initialStep [string]The step from the above set that the exchange starts on. Passing intialStep is REQUIRED. controller [string]The controller of the instance. Passing controller is OPTIONAL. authorization [object]Authorization scheme information (e.g., OAuth2 configuration). Passing authorization is OPTIONAL. It MUST be an object of the following form: oauth2 [object]OAuth2 configuration. It MUST be an object of the following form: issuerConfigUrl [string]OAuth2 issuer config URL. credentialTemplates [array]One or more VC templates for issuance. Passing credentialTemplates is OPTIONAL. Each item in the credentialTemplates array MUST be an object of the following form: type [string]The type of template. template [string]The template itself. steps [object]One or more steps required to complete an exchange on the workflow. The keys are one or more step names, where each STEP_NAME is replaced by the name of a step (such as request-employee-id), and the values are step configurations. It MUST be an object of the following form: STEP_NAME [object]Either Step data to be included if a template is not used. It MUST be an object of the following form: createChallenge [boolean]An optional step directive that tells the exchange to handle challenge management via a VC API verifier service it has a zcap for. verifiablePresentationRequest [object]A Verifiable Presentation Request. It MUST be an object of the following form: query [array]A set of one or more queries sent by the requester. Each item in the query array MUST be an object of the following form: type [array]The type of the query. Each item in the type array MUST be a string.challenge [string]A challenge, intended to prevent replay attacks, provided by the requester that is typically expected to be included in the Verifiable Presentation response. domain [string]A domain, intended to prevent replay attacks, provided by the requester that is typically expected to be included in the Verifiable Presentation response. interact [array]A list of interaction mechanisms that are supported by the server. Each item in the interact array MUST be an object of the following form: service [object]A service that is supported by the server that is capable of receiving a response to the Verifiable Presentation Request. It MUST be an object of the following form: type [array]The type of the service. Each item in the type array MUST be a string.serviceEndpoint [string]A URL that can be utilized for interacting with the service for the purposes of responding to the Verifiable Presentation Request. presentationSchemaEither A JSON Schema describing the validation to be performed on the presentation. It MUST be an object of the following form: type [string]The value MUST be JsonSchema. jsonSchema [object]an object or An alternate presentation schema format to use when validating a presentation in the current step. Additional properties are expected for a specific presentation schema type, but are beyond the scope of this specification. It MUST be an object of the following form: type [string]The type of presentation schema mechanism to use when validating the presentation. verifyPresentationResponseSchemaEither A JSON Schema describing the validation to be performed on the result of verifying the presentation. It MUST be an object of the following form: type [string]The value MUST be JsonSchema. jsonSchema [object]an object or An alternate presentation schema format to use on the result of verifying a presentation in the current step. Additional properties are expected for a specific presentation schema type, but are beyond the scope of this specification. It MUST be an object of the following form: type [string]The type of presentation schema mechanism to use when validating the result of verifying the presentation. nextStep [string]The name of the next step in the sequence. Passing nextStep is OPTIONAL. This field MUST NOT be present on the final step configuration. openId [object]Optional information to trigger OID4VP It MUST be an object of the following form: createAuthorizationRequest [string]If present, identifies the name of the template variable (in variables for an exchange) that the auto-generated OpenID for Verifiable Presentations Authorization Request will be stored in for subsequent use in the exchange. Either this or authorizationRequest MUST be present, but not both. The value of the named variable can be lazily generated when the Authorization Request is required, i.e., after the client of the exchange chooses to use the OID4VP protocol. This feature allows the Authorization Request to be generated by reusing values, e.g., a Verifiable Presentation Request, that only need to be specified once across multiple protocol offerings. authorizationRequest [object]an object or an object of the following form: stepTemplate [object]A template for a workflow step. Either this must be present or the other step data must be present, but not both sets. It MUST be an object of the following form: type [string]The type of template. template [string]The step template. content-type: application/json 400 Invalid input 401 Not Authorized 500 Internal Error 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. Create Exchange POST /workflows/{localWorkflowId}/exchanges - Creates a new exchange and returns location of exchange metadata in a response header. The /workflows/{localWorkflowId}/exchanges endpoint uses the following schema when receiving a POST: Property Description expires [string] The date and time (expressed as an XML Schema dateTimeStamp) that the exchange expires. variables [object] an object openId [object] an object The /workflows/{localWorkflowId}/exchanges endpoint can result in any of these responses when receiving a POST: Response Body 201 Exchange successfully created (with data) 204 Exchange successfully created (without data) 400 Invalid input 401 Not Authorized 500 Internal Error Get Exchange Protocols This endpoint provides a mechanism for a client to query an exchange for all of the protocols that it supports. A single exchange can support many protocols that are capable of achieving the goals of the exchange, such as the issuance of a verifiable credential into a digital wallet. GET /workflows/{localWorkflowId}/exchanges/{localExchangeId}/protocols - Gets the supported protocols for interacting with a specific exchange. The /workflows/{localWorkflowId}/exchanges/{localExchangeId}/protocols endpoint can result in any of these responses when receiving a GET: Response Body 200 Protocols understood by the exchange. Object containing information about the protocols that can be used to perform a specific exchange. It MUST be an object of the following form: protocols [object]An object containing one or more protocols that can be used to perform the specific exchange. It MUST be an object of the following form: interact [string]A URL that can be used during exchange flows with a human in the loop. See the section on the interact URL format for more details. vcapi [string]The URL to use when initiating a VC API exchange. OID4VP [string]The URL to use when initiating an OID4VP presentation. OID4VCI [string]The URL to use when initiating an OID4VCI issuance. content-type: application/json 400 Invalid input 401 Not Authorized 500 Internal Error This endpoint also enables the website operator to delegate the authority to execute the exchange to a third party, such as a service provider, by delegating that trust through the HTTPS domain. For example, the website brand.example can delegate the operation of the exchange to a partner saas.example by using the saas.example domain in the list of protocols. Exchange Service (saas.example)Issuer/Verifier Coordinator (brand.example)Holder Coordinator (Wallet)Exchange Service (saas.example)Issuer/Verifier Coordinator (brand.example)Holder Coordinator (Wallet)Wallet retrieves protocol optionsWallet selects a supported protocolGET /workflows/123/exchanges/456/protocols1Returns list of protocols understood by the exchange2Wallet picks protocol to saas.example3Wallet executes interaction protocol via saas.example4 Figure 3 An example of a wallet using a protocol to a delegated exchange service. This enables the client to depend on their trust in brand.example to delegate the operation of the exchange to a third party in the same way that a website links to resources from other domains to render a web page. Participate in an Exchange POST /workflows/{localWorkflowId}/exchanges/{localExchangeId} - Participate in an exchange. Posting an empty body will start the exchange or return what the exchange is expecting to complete the next step. Posting a Verifiable Presentation Request will result in either a 4xx error or one of the following - a Verifiable Presentation or Verifiable Presentation Request that conforms to the client's request. If a Verifiable Presentation is sent, an additional Verifiable Presentation Request may also be sent to continue the exchange. The /workflows/{localWorkflowId}/exchanges/{localExchangeId} endpoint uses one of the following schemas when receiving a POST: Property Description verifiablePresentationRequest [object] A Verifiable Presentation Request. It MUST be an object of the following form: query [array]A set of one or more queries sent by the requester. Each item in the query array MUST be an object of the following form: type [array]The type of the query. Each item in the type array MUST be a string.challenge [string]A challenge, intended to prevent replay attacks, provided by the requester that is typically expected to be included in the Verifiable Presentation response. domain [string]A domain, intended to prevent replay attacks, provided by the requester that is typically expected to be included in the Verifiable Presentation response. interact [array]A list of interaction mechanisms that are supported by the server. Each item in the interact array MUST be an object of the following form: service [object]A service that is supported by the server that is capable of receiving a response to the Verifiable Presentation Request. It MUST be an object of the following form: type [array]The type of the service. Each item in the type array MUST be a string.serviceEndpoint [string]A URL that can be utilized for interacting with the service for the purposes of responding to the Verifiable Presentation Request. Alternatively, the /workflows/{localWorkflowId}/exchanges/{localExchangeId} endpoint can also use the following schema: Property Description verifiablePresentation [object] an object of the following form: @context [array]The JSON-LD context of the presentation. Each item in the @context array MUST be a string.id [string]The ID of the presentation. type [array]The JSON-LD type of the presentation. Each item in the type array MUST be a string.holder [object]an objectverifiableCredential [array]The Verifiable Credentials Each item in the verifiableCredential array MUST be an object of the following form: @context [array]The JSON-LD context of the credential. Each item in the @context array MUST be a string.id [string]The ID of the credential. This property MAY be empty. The issuer SHOULD NOT auto-generate the id property if not provided, as a Verifiable Credential does not require the id property to be valid, and there are use cases for which the id property cannot be set. type [array]The JSON-LD type of the credential. Each item in the type array MUST be a string.issuer [object]Either a string or an object of the following form: id [string]The issuer id. issuanceDate [string]The issuanceDate expirationDate [string]The expirationDate credentialSubject [object]an objectproof [object]A Data Integrity Proof as defined by the W3C VC Data Integrity specification. It MUST be an object of the following form: type [string]Data Integrity Proof type. cryptosuite [string]The name of the cryptographic suite. created [string]Date the proof was created. nonce [string]A value chosen by the creator of a proof to randomize proof values for privacy purposes. verificationMethod [string]Verification Method used to verify proof. proofPurpose [string]The purpose of the proof to be used with verificationMethod. proofValue [string]Value of the Linked Data proof. proof [object]A Data Integrity Proof that includes a challenge and a domain as defined by the W3C VC Data Integrity specification. It MUST be an object of the following form: type [string]Data Integrity Proof type. cryptosuite [string]The name of the cryptographic suite. created [string]Date the proof was created. challenge [string]A value chosen by the verifier to mitigate authentication proof replay attacks. domain [string]The domain of the proof to restrict its use to a particular target. nonce [string]A value chosen by the creator of a proof to randomize proof values for privacy purposes. verificationMethod [string]Verification Method used to verify proof. proofPurpose [string]The purpose of the proof to be used with verificationMethod. proofValue [string]Value of the Linked Data proof. The /workflows/{localWorkflowId}/exchanges/{localExchangeId} endpoint can result in any of these responses when receiving a POST: Response Body 200 Exchange progressed. an object of the following form: verifiablePresentationRequest [object]A Verifiable Presentation Request. It MUST be an object of the following form: query [array]A set of one or more queries sent by the requester. Each item in the query array MUST be an object of the following form: type [array]The type of the query. Each item in the type array MUST be a string.challenge [string]A challenge, intended to prevent replay attacks, provided by the requester that is typically expected to be included in the Verifiable Presentation response. domain [string]A domain, intended to prevent replay attacks, provided by the requester that is typically expected to be included in the Verifiable Presentation response. interact [array]A list of interaction mechanisms that are supported by the server. Each item in the interact array MUST be an object of the following form: service [object]A service that is supported by the server that is capable of receiving a response to the Verifiable Presentation Request. It MUST be an object of the following form: type [array]The type of the service. Each item in the type array MUST be a string.serviceEndpoint [string]A URL that can be utilized for interacting with the service for the purposes of responding to the Verifiable Presentation Request. or an object of the following form: verifiablePresentation [object]an object of the following form: @context [array]The JSON-LD context of the presentation. Each item in the @context array MUST be a string.id [string]The ID of the presentation. type [array]The JSON-LD type of the presentation. Each item in the type array MUST be a string.holder [object]an objectverifiableCredential [array]The Verifiable Credentials Each item in the verifiableCredential array MUST be an object of the following form: @context [array]The JSON-LD context of the credential. Each item in the @context array MUST be a string.id [string]The ID of the credential. This property MAY be empty. The issuer SHOULD NOT auto-generate the id property if not provided, as a Verifiable Credential does not require the id property to be valid, and there are use cases for which the id property cannot be set. type [array]The JSON-LD type of the credential. Each item in the type array MUST be a string.issuer [object]Either a string or an object of the following form: id [string]The issuer id. issuanceDate [string]The issuanceDate expirationDate [string]The expirationDate credentialSubject [object]an objectproof [object]A Data Integrity Proof as defined by the W3C VC Data Integrity specification. It MUST be an object of the following form: type [string]Data Integrity Proof type. cryptosuite [string]The name of the cryptographic suite. created [string]Date the proof was created. nonce [string]A value chosen by the creator of a proof to randomize proof values for privacy purposes. verificationMethod [string]Verification Method used to verify proof. proofPurpose [string]The purpose of the proof to be used with verificationMethod. proofValue [string]Value of the Linked Data proof. proof [object]A Data Integrity Proof that includes a challenge and a domain as defined by the W3C VC Data Integrity specification. It MUST be an object of the following form: type [string]Data Integrity Proof type. cryptosuite [string]The name of the cryptographic suite. created [string]Date the proof was created. challenge [string]A value chosen by the verifier to mitigate authentication proof replay attacks. domain [string]The domain of the proof to restrict its use to a particular target. nonce [string]A value chosen by the creator of a proof to randomize proof values for privacy purposes. verificationMethod [string]Verification Method used to verify proof. proofPurpose [string]The purpose of the proof to be used with verificationMethod. proofValue [string]Value of the Linked Data proof. an object of the following form: redirectUrl [string]The URL the exchange wishes to redirect the client to. content-type: application/json 400 Invalid input 401 Not Authorized 500 Internal Error Get Exchange State GET /workflows/{localWorkflowId}/exchanges/{localExchangeId} - Gets the state of an existing exchange and returns it in the response body. The /workflows/{localWorkflowId}/exchanges/{localExchangeId} endpoint can result in any of these responses when receiving a GET: Response Body 200 Exchange configuration retrieved! Object containing information about an active exchange. It MUST be an object of the following form: id [string]The local exchange ID that identifies the exchange. sequence [integer]A sequence number for the exchange. Set to 0 on creation. expires [string]The date and time (expressed as an XML Schema dateTimeStamp) that the exchange expires. step [string]The current step in the exchange. state [string]The status ("pending" | "active" | "complete" | "invalid") of the exchange, set to "pending" on creation. variables [object]an object content-type: application/json 400 Invalid input 401 Not Authorized 500 Internal Error Exchange Examples The APIs in this specification enables unmediated (automated, machine-to-machine) or mediated (person in the loop) exchanges to be executed. These exchanges are initiated by a holder coordinator and responded to by any Coordinator that implements exchanges. The flows consist of the following steps: 1. The holder coordinator contacts the receiving Coordinator to request the initiation of a particular exchange. 2. The receiving Coordinator responds with a presentation request of some kind to authenticate and/or authorize the holder coordinator and provides the next hop in the exchange as a URL. 3. The holder coordinator responds to the receiving Coordinator with a Verifiable Presentation containing information that will satisfy the presentation request. 4. The receiving Coordinator responds with a Verifiable Presentation with the newly issued Verifiable Credentials or a further presentation request as expressed in step 2 above. The holder coordinator MAY call the Coordinator's exchange discovery endpoint to determine if the holder coordinator supports the Coordinator's protocol requirements on a particular endpoint, before actually initiating the exchange. A diagram of the steps outlined above is presented below: Issuer/Verifier CoordinatorHolder Coordinator (Wallet)HolderIssuer/Verifier CoordinatorHolder Coordinator (Wallet)HolderStart exchangePOST /workflows/123/exchanges/abc — HTTP request to start exchange (e.g., send credentials, get credentials)VPR includes method of interaction, for purposes of exchangePOST /workflows/123/exchanges/abc — sent via interaction mechanism to meet requirements of exchangeVP includes result of exchange (e.g., VCs), or VPR with new interaction request, or error descriptionInitiate1Verifiable Presentation Request (VPR)2Verifiable Presentation (VP)3Verifiable Presentation4 Figure 4 A standard exchange between a holder and an issuer / verifier . Note The general exchange above can be performed in a way that is fully automated, mediated by a person, or in a hybrid fashion where portions are automated but interaction by a person is required at certain stages. The second step above is used to provide guidance on whether the next step is automated or requires an individual to intervene. Initiating Interactions 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. Note : Interactions are application, use case, and protocol agnostic While several interaction specifications reside in this document, the general approach is agnostic as to use case, application, and protocol. This approach can be used to pair two or more applications that desire to bootstrap into a particular protocol over any transmission medium — such as a web browser, QR Code (optical medium), or NFC (wireless medium) — where the protocol does not need to involve this API. 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: Issuer CoordinatorBrowserHolder Coordinator (Wallet)HolderIssuer CoordinatorBrowserHolder Coordinator (Wallet)Holderhttps://issuer.example/interactions/123?iuv=1GET https://issuer.example/interactions/123?iuv=1(VCALM, OID4VP, NFC, Bluetooth, etc.)issuer.example is offering credentials, accept?opt["vcapi" protocol example]Click "Receive credential"1Request interaction QR Code2Generate QR Code3Display QR Code4Start scanning QR Code5Scan QR Code6Get available interaction protocols7Return interaction protocols8Select appropriate protocol9Initiate workflow exchange10Acquire consent to proceed11 Figure 5 An issuer-initiated interaction using a QR Code 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: Verifier CoordinatorBrowserHolder Coordinator (Wallet)HolderVerifier CoordinatorBrowserHolder Coordinator (Wallet)Holderhttps://verifier.example/interactions/123?iuv=1GET https://verifier.example/interactions/123?iuv=1(VCALM, OID4VP, NFC, Bluetooth, etc.)verifier.example is requesting credentials, proceed?opt["vcapi" protocol example]Click "Share credential"1Request interaction QR Code2Generate QR Code3Display QR Code4Start scanning QR Code5Scan QR Code6Get available interaction protocols7Return interaction protocols8Acquire consent to proceed9Select appropriate protocol10Initiate workflow exchange11 Figure 6 A verifier-initiated interaction using a QR Code 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: Verifier CoordinatorHolder Coordinator (Wallet)HolderVerifier CoordinatorHolder Coordinator (Wallet)HolderGET https://wallet.example/interactions/456?iuv=1(VCALM, OID4VP, NFC, Bluetooth, etc.)"Open browser to verifier.example?"opt["inviteRequest" protocol example]Tap "Share credential"1Generate Interaction URL2Display QR Code3Present QR Code4Scan QR Code and decode URL5Get available interaction protocols6Return interaction protocols7Select appropriate protocol8Transmit protocol selection and options9Request consent to proceed10Confirm consent to go to website11Go to website12 Figure 7 A holder-initiated interaction using a QR Code Interaction URL Format The format of the interaction URL MUST conform to the syntax for the URL Standard and contain an iuv query parameter encoding the interaction URL version number, which MUST be 1 when using this version of this API. The interaction URL SHOULD be an HTTPS URL that contains an interaction-specific identifier. The URL SHOULD be opaque and require no URL syntax processing before it is fetched by the receiving system. An example of such a URL is shown below: Example 12 : An interaction URL https://app.example/interactions/z8n38Dp7a?iuv=1 Protocols that encode lengthy protocol-specific information into URLs suffer from limitations placed by software libraries on the maximum allowable length of a URL. At the time of writing, the suggested URL length limit is roughly 2,000 characters. Implementers SHOULD NOT put information that can be expressed in the response to a GET request for an interaction URL, defined in Section Interaction Protocols Response, into the query parameters of the interaction URL. 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: Figure 8 An interaction QR code for https://app.example/interactions/z8n38Dp7a?iuv=1 Interaction Protocols Response Performing a retrieval of the interaction URL results in instructions on how to start an interaction with the remote system. When the interaction URL is fetched using an Accept header of application/json, a single JSON object containing a protocols map MUST be returned where each key is a protocol identifier and each value is a URL that can be used to initiate the interaction. For example, performing an HTTP GET on the https://app.example/interactions/z8n38Dp7a?iuv=1 interaction URL might result in either of the following responses: Example 13 : A list of protocols supported for a given interaction, with inviteRequest being generated by the Workflow Service in use. { "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'" } } Example 14 : The degenerate case where the list of protocols only includes the inviteRequest option. { "protocols": { "inviteRequest": "https://saas.example/interaction/123/invite-request/response" } } The protocol response enables protocol execution to be delegated to third-party service providers through the HTTPS domain trust model, similar to the delegation mechanism described in the Get Exchange Protocols section. For example, the website app.example can delegate the operation of the exchange to a partner saas.example by including the saas.example domain in the list of protocols. When the interaction URL is fetched using any unrecognized Accept header, a text/html document MUST be returned with directions instructing a human being to use specific software that understands how to process interaction URLs. Note : Mapping to exchange URLs Some coordinator implementations will implement the protocols endpoint as a pass through to a protocols endpoint for an exchange instance. For example, a GET on https://app.example/interactions/z8n38Dp7a?iuv=1 will result in a pass-through GET on https://app.example/workflows/123/exchanges/987/protocols, which would return the response above. Implementing interaction URLs in this way can provide an easier implementation path. inviteRequest Interaction Protocol The inviteRequest interaction protocol is used by a local system to signal to the remote system that it would like an invitation to a remote system via a specific URL, such as a website where an individual can engage in a use-case specific interaction. If the inviteRequest interaction protocol is selected, the local system sends data using an HTTP POST to instruct the remote system where to send the individual. A couple examples of the POST data are shown below. These examples intend to highlight that this specification does not state any requirements as to how the "url" field is formatted, but does recommend that an implimenter of this interaction mechanism make use of a unique ID: Example 15 : A response to an invitation request, for checking out at a store { "url": "https://website.example/checkout/8372974", "purpose": "Checkout at ShopCo", "referenceId": "417bcaf2-14d9-11f0-99d7-9f094678517b" } Example 16 : A response to an invitation request, to fill out an online form { "url": "https://website.example/forms/7864165", "purpose": "Fill out online form", "referenceId": "d4a6e5b8-1715-4654-8e47-e68b311756d1" } vcapi Interaction Protocol The vcapi interaction protocol is used to initiate a specific exchange as described in Section Participate in an Exchange. Example 17 : A VC-API interaction protocol request { "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" } } Error Handling 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. Example 18 : An example of a ProblemDetails object { "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." } Issue 4 The example type URLs above 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. 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. Verification Errors vs. Warnings This specification defines a distinction between a verification error and a verification warning. Errors are ProblemDetails relating to cryptography, data model, and malformed context and are unrecoverable. Warnings are ProblemDetails relating to status and validity periods and might be recoverable or leave the subsequent action to the discretion of the application. If an error is included, the verified property of the VerificationResponse object MUST be set to false; if no errors are included, it MUST be set to true. Example 19 : An example verification response containing warnings and errors. { "verified": false, "document": verifiableCredential, "mediaType": "application/vc", "controller": issuer, "controllerDocument": didDocument, "warnings": [ProblemDetails], "errors": [ProblemDetails] } A. Privacy Considerations A.1 Delegation Verifiable credentials [VC-DATA-MODEL-2.0] are a standard data model designed to mitigate risks of misuse and fraud. As a data model, verifiable credentials are protocol-neutral and consider at least two types of entities: issuer and subject. When the subject of a verifiable credential is a natural person or linked to a natural person, privacy and human rights can be impacted by the vastly more efficient processing of standardized verifiable credentials as compared to their analog ancestors. Technology, in the form of standardized APIs and protocols for issuing verifiable credentials, further enhances the efficiency of processing verifiable credentials and adds to the risks of unforeseen privacy and human rights consequences. Verifiable credentials issuance has a request phase and a delivery phase. The request might be made by the subject or another role, and delivery can be to a client that might or might not be controlled by the subject. Delegation is highly relevant for both phases. The issuer might delegate processing of the request to a separate entity. The subject, for their part, might also delegate the ability to request a verifiable credential to a separate entity. Note that the subject might not always have the capability or ability to perform delegation. Examples include a new born baby, a pet, and a person with dementia. So the request might be performed by a third party who was not delegated by the subject. The ability to delegate is a third dimension in the enhanced efficiency of processing verifiable credentials and has impact on privacy and human rights. The architecture described in this specification is designed for market acceptance through a combination of efficiency and respect for privacy and human rights. APIs and protocols for processing verifiable credentials do not favor delegation by the issuer role over delegation by the subject role. A.2 "Phoning Home" Considered Harmful It is considered a bad privacy practice for a verifier to contact an issuer about a specific verifiable credential. This practice is known as "phoning home" and can result in a mismatch in privacy expectations between holders, issuers, verifiers, and other parties expressed in a verifiable credential. Phoning home enables issuers to correlate unsuspecting parties with the use of certain verifiable credentials which can violate privacy expectations that each entity might have regarding the use of those credentials. For example, what is expected by the holder to be a private interaction between them and the verifier becomes one where the issuer is notified of the interaction. There are some interactions where contacting the issuer in a privacy-preserving manner upholds the privacy expectations of the holder. For example, contacting the issuer to get revocation status information in a privacy-respecting manner, such as through a status list that provides group privacy can be acceptable as long as the issuer is not able to single out which verifiable credential is being queried based on the retrieval of the status list. For more information on one such mechanism see the Bitstring Status List v1.0 specification. Verifiers are urged to not "phone home" in ways that will create privacy violations. When retrieving content that is linked from a verifiable credential, using mechanisms such as Oblivious HTTP and aggressively caching results can improve the privacy characteristics of the ecosystem. B. Security Considerations B.1 Unknown Proof Types Holder coordinator implementations, such as digital wallet software, can receive and store verifiable credentials that include proofs that are not understood by the software, however, these proofs are not to be presented by the implementation. A verifiable credential with several proofs, some of which the implementation understands and others that it does not, can be presented by the implementation provided that the proof of choice is understood by the implementation and the others are removed prior to presentation. Implementations maintain allow lists of understood proofs and ensure that any proofs not present are stripped prior to presentation. Implementations can use the presence of unknown proofs as potential adoption signals in a decentralized ecosystem. It is also important for implementers to understand that in the three party model, the holder coordinator acts as a conduit between the issuer and the verifier, enabling interoperability between the two even if/when the holder coordinator doesn't necessarily implement verification of certain proofs. As an example in another space: "Web browsers were able to download and store PDF files prior to adding their own PDF-reader functionality" — this kind of decentralized innovation, interoperability, and progressive enhancement is important in the three party model and more generally in scalable, decentralized ecosystems. It is also important to help reduce centralization by not forcing people to adopt specific new and different software just to store a verifiable credential that has at least one proof on it that their current software does not (yet) understand. A holder coordinator might be able to present some proofs even when it does not have the software to verify them, but this needs to be understood with certainty, not guessed. That is, when adding a copy of a stored verifiable credential to a presentation, holder software needs to remove any proofs that it does not explicitly know it can safely present. Any proofs that software does explicitly know it can safely present can remain. For example, a digital wallet that can verify an ecdsa-rdfc-2019 proof, but not an ecdsa-jcs-2019 proof, can still present either. Other proofs, such as those that offer selective disclosure and / or unlinkable disclosure features require transformation (that is, a base proof is transformed to a derived proof plus a "reveal document") and, therefore, a wallet will not be able to present these proofs unless the wallet has implemented the procedures for deriving a proof. It is vital that a wallet not present a base proof by accident, as it might include information that is secret to the holder. B.2 Use of HTTPS for Interaction URLs This specification strongly suggests the use of HTTPS for interaction URLs for the following reasons: * The HTTPS URL used in an interaction firmly establishes trust in the interaction based on the existing and well understood same-origin trust model used by browsers. * The initial URL provided establishes trust such that subsequent protocols used in the interaction can be simply and safely delegated or outsourced to other systems, some of which can be in a separate domain. * Graphical interfaces that need to gather consent can use domain names, which are understood well enough by the general population to combat phishing attacks. * Protocols that require stronger verification of any party can use protocol-specific mechanisms, such as verifiable credentials, to verify the holder, issuer, or verifier during a particular protocol exchange. Using protocol schemes that are not rooted in the HTTPS trust model requires separate encryption protocol, key management, and trust models to be used, which are often less broadly developed and deployed and require much more development and analysis to determine the threat and privacy model. B.3 Deletion The APIs provided by this specification enable the deletion of verifiable credentials and verifiable presentations from storage services. The result of these deletions and the side-effects they might cause are out of scope for this specification. However, implementers are advised to understand the various ways deletion can be implemented. There are at least two types of deletion that are contemplated by this specification. Partial deletion marks a record for deletion but continues to store some or all of the original information. This mode of operation can be useful if there are audit requirements for all credentials and/or presentations over a particular time period, or if recovering an original credential might be a useful feature to provide. Complete deletion purges all information related to a given verifiable credential or verifiable presentation in a way that is unrecoverable. This mode of operation can be useful when removing information that is outdated and beyond the needs of any audit or when responding to any sort of "right to be forgotten" request. When deleting a verifiable credential, handling of its status information needs to be considered. Some use cases might call for deletion of a particular verifiable credential to also set the revocation and suspension bits of that verifiable credential, such that any sort of status check for the deleted credential fails and use of the credential is halted. Given the scenarios above, implementers are advised to allow the system actions that occur after a delete to be configurable, such that system flexibility is sufficient to address any verifiable credential use case. B.4 Payload Sizes Larger transactions can trigger DoS incidents. It's recommended to configure the payload size accepted by endpoints at an instance level. B.5 Additional Validation In most cases, simply verifying the proof might not be sufficient to properly handle the received data. Verifier services are expected to configure additional validation steps based on their use cases. To define such additional validations, implementers can refer to specifications such as Section 2.3: Resource Integrity and Section 2.4: Contexts and Vocabularies in the Verifiable Credential Data Integrity 1.0 specification where further information can be found about context handling and integrity verification. Improper validation will often lead to security vulnerabilities. Additional validation steps can be accounted for when returning a verification response object, through the problem details. B.6 Secure Coding Practices Implementers are urged to use industry standard secure coding practices when implementing this specification. Even deeply experienced software developers can make mistakes and the use of secure coding checklists and vulnerability scanning software can catch errors that would result in security compromises. Following checklists and guides such as the OWASP Secure Coding Practices Checklist and the OWASP Web Security Testing Guide can help reduce the chance of insecure implementations. B.7 Other Security Considerations Since the interfaces to manage the lifecycle of verifiable credentials described by this specification are generalized in nature, the security implications of their use might not be immediately apparent to readers. To understand the sort of security concerns one might need to consider in a complete software system, implementers are urged to read about how this technology can be used by the Verifiable Credentials Data Model v2.0 specification (specifically the section on Verifiable Credential Security Considerations), as well as the Verifiable Credential Data Integrity 1.0 specification (specifically the section on Data Integrity Security Considerations). C. Relationship to Other Specifications The lifecycle of a verifiable credential includes the creation of a workflow, an initial interaction to engage in an exchange, issuance, status management, local credential administration, presentation, verification, and validation. This specification defines an HTTP-based API for verifiable credential lifecycle management that can be used by issuers, holders, and verifiers. There are other specifications, such as the Digital Credential API, OpenID for Verifiable Credential Issuance v1.0, and OpenID for Verifiable Presentations v1.0 that might seem to provide similar functionality to this specification. This section explains what other specifications have been considered before the standardization of this specification, and how this specification differs from other specifications in the ecosystem. Fundamentally, this specification is the only specification that is focused on the entire lifecycle management of verifiable credentials. It is agnostic to credential format, credential query language, and credential delivery protocol. Any credential format that is expressible as a verifiable credential or an enveloped verifiable credential can be used with this specification. Similarly, credential delivery protocols such as OpenID for Verifiable Credential Issuance v1.0 or OpenID for Verifiable Presentations v1.0 can be used in interactions and exchanges defined by this specification. Finally, this specification supports multiple credential query languages to provide for flexibility as technologies improve and market verticals specialize. This specification defines APIs for the entirety of verifiable credential lifecycle management because not doing so creates opportunities for vendor lock-in. No other specification exists that provides interfaces that prevent vendor lock throughout the lifecycle management of verifiable credentials. D. Acknowledgements The Working Group thanks the following individuals for their contributions to this specification: The final list of acknowledgements will be compiled at the end of the Candidate Recommendation phase. Portions of the work on this specification have been funded by the United States Department of Homeland Security's Silicon Valley Innovation Program under contracts 70RSAT20T00000003, 70RSAT20T00000010, 70RSAT20T00000029, 70RSAT20T00000031, 70RSAT20T00000033, and 70RSAT20T00000043. The content of this specification does not necessarily reflect the position or the policy of the U.S. Government and no official endorsement should be inferred. Development of this specification has also been supported by the W3C Credentials Community Group, chaired by Kim Hamilton Duffy, Heather Vescent, and Wayne Chang. E. References E.1 Normative references [DCAPI] Digital Credential API. W3C. W3C Working Draft. URL: https://www.w3.org/TR/digital-credentials/ [infra] Infra Standard. Anne van Kesteren; Domenic Denicola. WHATWG. Living Standard. URL: https://infra.spec.whatwg.org/ [ISO18004] ISO18004:2024: QR Code Bar Code Symbology Specification. ISO. Published. URL: https://www.iso.org/standard/83389.html [OID4VCI] OpenID for Verifiable Credential Issuance v1.0. OpenID Foundation. W3C Working Draft. URL: https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html [OID4VP] OpenID for Verifiable Presentations v1.0. OpenID Foundation. W3C Working Draft. URL: https://openid.net/specs/openid-4-verifiable-presentations-1_0.html [RFC2119] Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119 [RFC6749] The OAuth 2.0 Authorization Framework. D. Hardt, Ed. IETF. October 2012. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc6749 [RFC6750] The OAuth 2.0 Authorization Framework: Bearer Token Usage. M. Jones; D. Hardt. IETF. October 2012. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc6750 [RFC7617] The 'Basic' HTTP Authentication Scheme. J. Reschke. IETF. September 2015. Proposed Standard. URL: https://httpwg.org/specs/rfc7617.html [RFC8174] Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174 [RFC9457] Problem Details for HTTP APIs. M. Nottingham; E. Wilde; S. Dalal. IETF. July 2023. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc9457 [URL] URL Standard. Anne van Kesteren. WHATWG. Living Standard. URL: https://url.spec.whatwg.org/ [VC-BITSTRING-STATUS-LIST] Bitstring Status List v1.0. Manu Sporny; Dave Longley; Mahmoud Alkhraishi; Michael Prorock. W3C. 15 May 2025. W3C Recommendation. URL: https://www.w3.org/TR/vc-bitstring-status-list/ [VC-DATA-INTEGRITY] Verifiable Credential Data Integrity 1.0. Ivan Herman; Manu Sporny; Ted Thibodeau Jr; Dave Longley; Greg Bernstein. W3C. 15 May 2025. W3C Recommendation. URL: https://www.w3.org/TR/vc-data-integrity/ [VC-DATA-MODEL-2.0] Verifiable Credentials Data Model v2.0. Ivan Herman; Michael Jones; Manu Sporny; Ted Thibodeau Jr; Gabe Cohen. W3C. 15 May 2025. W3C Recommendation. URL: https://www.w3.org/TR/vc-data-model-2.0/ E.2 Informative references [DID-CORE] Decentralized Identifiers (DIDs) v1.0. Manu Sporny; Amy Guy; Markus Sabadello; Drummond Reed. W3C. 19 July 2022. W3C Recommendation. URL: https://www.w3.org/TR/did-core/ [json-schema] JSON Schema: A Media Type for Describing JSON Documents. Austin Wright; Henry Andrews; Ben Hutton; Greg Dennis. Internet Engineering Task Force (IETF). 10 June 2022. Internet-Draft. URL: https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema [RFC9458] Oblivious HTTP. M. Thomson; C. A. Wood. IETF. January 2024. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc9458 ↑ Permalink Referenced in: * § Verifiable Presentation Request (2) Permalink exported Referenced in: * Not referenced in this document. Permalink exported Referenced in: * Not referenced in this document. Permalink Referenced in: * § C. Relationship to Other Specifications Permalink Referenced in: * § vcapi Interaction Protocol * § C. Relationship to Other Specifications (2) Permalink Referenced in: * § C. Relationship to Other Specifications Permalink Referenced in: * § Interaction QR Code Format (2) * § Interaction Protocols Response (2) (3) (4) Permalink Referenced in: * Not referenced in this document. Permalink Referenced in: * § Error Handling (2) Permalink Referenced in: * Not referenced in this document. Permalink Referenced in: * Not referenced in this document. | If you are not redirected automatically, follow this link to the new website. |
For now, Differences are performed on text, not graphically, only the latest screenshot is available.
Screenshot requires Playwright/WebDriver enabled