openapi: 3.0.0 servers: - url: https://verifier.qa.veres.app/verifiers/z1A45ZhWEGMeibHrB15nv8Gk6 description: Veres Verifier (Quality Assurance) info: version: "0.9-unstable" title: Verifiable Credential API for Lifecycle Management description: Provides the data model and HTTP APIs to issue, verify, present, and manage data used in the Verifiable Credentials ecosystem. license: name: W3C Software and Document License url: http://www.w3.org/Consortium/Legal/copyright-software. contact: name: GitHub Source Code url: https://github.com/w3c/vcalm paths: /credentials/issue: post: summary: Issues a credential and returns it in the response body. tags: - Credentials security: - networkAuth: [] - oAuth2: [] - zCap: [] operationId: issueCredential x-expectedCaller: - Issuer Coordinator - Workflow Service x-componentTableLink: "issue-credential" description: Issues a credential and returns it in the response body. requestBody: content: application/json: schema: $ref: "#/components/schemas/IssueCredentialRequest" description: Parameters for issuing the credential. responses: "201": description: Credential successfully issued! content: application/json: schema: $ref: "#/components/schemas/IssueCredentialResponse" "400": description: > 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. /credentials/status: post: summary: Updates the status of an issued credential tags: - Credentials security: - networkAuth: [] - oAuth2: [] - zCap: [] operationId: updateCredentialStatus x-expectedCaller: Issuer Service x-componentTableLink: "update-status" description: Updates the status of an issued credential. requestBody: content: application/json: schema: $ref: "#/components/schemas/UpdateCredentialStatusRequest" description: Parameters for updating the status of the issued credential. responses: "200": description: Credential status successfully updated "400": description: Bad Request "404": description: Credential not found /status-lists: post: summary: Creates a new status list tags: - Credentials security: - networkAuth: [] - oAuth2: [] - zCap: [] operationId: createStatusList x-expectedCaller: Issuer Service x-componentTableLink: create-status-list description: Creates a new status list credential that can be used to track the status of verifiable credentials. The status list is returned as a verifiable credential that can be publicly accessible for verification purposes. requestBody: content: application/json: schema: $ref: "#/components/schemas/CreateStatusListRequest" description: Parameters for creating a status list. responses: "201": description: Status list successfully created content: application/json: schema: $ref: "#/components/schemas/CreateStatusListResponse" headers: Location: schema: type: string format: uri description: The HTTP URL used to retrieve the status list credential. example: https://issuer.example.com/credentials/status/lists/abc123 "400": description: Bad Request /status-lists/{id}: get: summary: Retrieves a status list credential tags: - Credentials security: [] operationId: getStatusList x-expectedCaller: Public x-componentTableLink: get-status-list description: Retrieves a publicly accessible status list credential. This endpoint SHOULD be publicly accessible without authentication to enable verifiers and holders to retrieve status information. For privacy-preserving status mechanisms, verifiers SHOULD obtain status information from holders rather than directly querying this endpoint. parameters: - name: id in: path required: true schema: type: string description: The identifier of the status list credential to retrieve. responses: "200": description: Status list credential successfully retrieved content: application/json: schema: $ref: "./components/VerifiableCredential.yml#/components/schemas/VerifiableCredential" "404": description: Status list not found /workflows: post: summary: Creates a new workflow and returns location of workflow metadata in a response header. tags: - Credentials security: - networkAuth: [] - oAuth2: [] - zCap: [] operationId: createWorkflow description: Creates a new workflow and returns location of workflow metadata in a response header. x-expectedCaller: Administrators x-componentTableLink: "create-workflow" requestBody: content: application/json: schema: $ref: "#/components/schemas/CreateWorkflowRequest" responses: "201": description: Workflow successfully created (with data) headers: Location: schema: type: string format: uri description: The HTTP URL used to retrieve workflow metadata. example: https://issuer.example.com/workflows/123 "204": description: Workflow successfully created (without data) headers: Location: schema: type: string format: uri description: The HTTP URL used to retrieve workflow metadata. example: https://issuer.example.com/workflows/123 "400": description: Invalid input "401": description: Not Authorized "500": description: Internal Error /workflows/{localWorkflowId}: get: summary: Gets the configuration of an existing workflow and returns it in the response body. tags: - Credentials security: - networkAuth: [] - oAuth2: [] - zCap: [] operationId: getWorkflowConfiguration description: Gets the configuration of an existing workflow and returns it in the response body. x-expectedCaller: Administrators x-componentTableLink: "get-workflow-configuration" parameters: - $ref: "./components/parameters/path/LocalWorkflowId.yml" responses: "200": description: Workflow configuration retrieved! content: application/json: schema: $ref: "#/components/schemas/GetWorkflowResponse" "400": description: Invalid input "401": description: Not Authorized "500": description: Internal Error /workflows/{localWorkflowId}/exchanges: post: summary: Creates a new exchange and returns location of exchange metadata in a response header. tags: - Credentials security: - networkAuth: [] - oAuth2: [] - zCap: [] operationId: createExchange description: Creates a new exchange and returns location of exchange metadata in a response header. x-expectedCaller: Coordinator x-componentTableLink: "create-exchange" parameters: - $ref: "./components/parameters/path/LocalWorkflowId.yml" requestBody: content: application/json: schema: $ref: "#/components/schemas/CreateExchangeRequest" responses: "201": description: Exchange successfully created (with data) headers: Location: schema: type: string format: uri description: The HTTP URL used to retrieve exchange metadata. example: https://issuer.example.com/workflows/123/exchanges/abc "204": description: Exchange successfully created (without data) headers: Location: schema: type: string format: uri description: The HTTP URL used to retrieve exchange metadata. example: https://issuer.example.com/workflows/123/exchanges/abc "400": description: Invalid input "401": description: Not Authorized "500": description: Internal Error /workflows/{localWorkflowId}/exchanges/{localExchangeId}: get: summary: Gets the state of an existing exchange and returns it in the response body. tags: - Credentials security: - networkAuth: [] - oAuth2: [] - zCap: [] operationId: getExchangeConfiguration description: Gets the configuration of an existing exchange and returns it in the response body. x-expectedCaller: Coordinator x-componentTableLink: "get-exchange-state" parameters: - $ref: "./components/parameters/path/LocalWorkflowId.yml" - $ref: "./components/parameters/path/LocalExchangeId.yml" responses: "200": description: Exchange configuration retrieved! content: application/json: schema: $ref: "#/components/schemas/GetExchangeResponse" "400": description: Invalid input "401": description: Not Authorized "500": description: Internal Error post: summary: 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 - 1. one or more Verifiable Presentations or 2. a Verifiable Presentation Request that conforms to the client's request. If one or more Verifiable Presentations are sent, an additional Verifiable Presentation Request may also be sent to continue the exchange. tags: - Credentials security: - networkAuth: [] - oAuth2: [] - zCap: [] operationId: participateInExchange description: Participate in an exchange. Posting an empty body will start the exchange or return what the exchange is expecting to complete the next step. x-expectedCaller: Anyone x-componentTableLink: "participate-in-an-exchange" parameters: - $ref: "./components/parameters/path/LocalWorkflowId.yml" - $ref: "./components/parameters/path/LocalExchangeId.yml" requestBody: content: application/json: schema: $ref: "#/components/schemas/ExchangeParticipationClientMessage" responses: "200": description: Exchange progressed. content: application/json: schema: $ref: "#/components/schemas/ExchangeParticipationServerMessage" "400": description: Invalid input "401": description: Not Authorized "500": description: Internal Error /workflows/{localWorkflowId}/exchanges/{localExchangeId}/protocols: get: summary: Gets the supported protocols for interacting with a specific exchange. tags: - Exchanges security: - networkAuth: [] - oAuth2: [] - zCap: [] operationId: getSupportedProtocolsConfiguration description: Gets the supported protocols for interacting with a specific exchange. x-expectedCaller: - Verifier Coordinator - Holder Coordinator x-componentTableLink: "get-exchange-protocols" parameters: - $ref: "./components/parameters/path/LocalWorkflowId.yml" - $ref: "./components/parameters/path/LocalExchangeId.yml" responses: "200": description: Protocols understood by the exchange. content: application/json: schema: $ref: "#/components/schemas/GetExchangeProtocolsResponse" "400": description: Invalid input "401": description: Not Authorized "500": description: Internal Error /credentials/{id}: get: tags: - Credentials security: - networkAuth: [] - oAuth2: [] - zCap: [] summary: 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. x-expectedCaller: - Issuer Coordinator - Holder Coordinator - Workflow Service x-componentTableLink: "get-a-specific-credential" operationId: getCredential parameters: - $ref: "./components/parameters/path/ObjectId.yml" responses: "200": description: Credential retrieved content: application/json: schema: oneOf: - $ref: "./components/VerifiableCredentialResponse.yml#/components/schemas/VerifiableCredentialResponse" "400": description: Bad Request "401": description: Not Authorized "404": description: Credential not found "410": description: Gone! There is no data here "418": description: I'm a teapot - MUST not be returned outside of pre-arranged scenarios between both parties delete: tags: - Credentials security: - networkAuth: [] - oAuth2: [] - zCap: [] summary: 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. x-expectedCaller: - Issuer Coordinator - Holder Coordinator x-componentTableLink: "delete-a-specific-credential" operationId: deleteCredential parameters: - $ref: "./components/parameters/path/ObjectId.yml" responses: "202": description: Credential deleted - this is a 202 by default as soft deletes and processing time are assumed "400": description: Bad Request "401": description: Not Authorized "404": description: Credential not found "410": description: Gone! There is no data here /credentials/derive: post: tags: - Credentials security: - networkAuth: [] - oAuth2: [] - zCap: [] summary: Derives a credential and returns it in the response body. operationId: deriveCredential description: Derives a credential and returns it in the response body. x-expectedCaller: - Holder Coordinator - Workflow Service x-componentTableLink: "derive-credential" requestBody: content: application/json: schema: $ref: "#/components/schemas/DeriveCredentialRequest" description: Parameters for deriving the credential. responses: "201": description: Credential derived successfully. content: application/json: schema: $ref: "#/components/schemas/DeriveCredentialResponse" "400": description: Invalid Request /presentations/{id}: get: tags: - Presentations summary: Gets a presentation or verifiable presentation by ID security: - networkAuth: [] - oAuth2: [] - zCap: [] operationId: getPresentation x-expectedCaller: - Holder Coordinator - Workflow Service x-componentTableLink: "get-a-specific-presentation" parameters: - $ref: "./components/parameters/path/ObjectId.yml" responses: "200": description: Credential retrieved content: application/json: schema: oneOf: - $ref: "./components/Presentation.yml#/components/schemas/Presentation" - $ref: "./components/VerifiablePresentation.yml#/components/schemas/VerifiablePresentation" "400": description: Bad Request "401": description: Not Authorized "404": description: Presentation not found "410": description: Gone! There is no data here delete: tags: - Presentations summary: Deletes a presentation or verifiable presentation by ID security: - networkAuth: [] - oAuth2: [] - zCap: [] operationId: deletePresentation x-expectedCaller: Holder Coordinator x-componentTableLink: "delete-a-specific-presentation" parameters: - $ref: "./components/parameters/path/ObjectId.yml" responses: "202": description: Presentation deleted - this is a 202 by default as soft deletes and processing time are assumed "400": description: Bad Request "401": description: Not Authorized "404": description: Presentation not found "410": description: Gone! There is no data here /presentations: get: tags: - Presentations summary: Gets list of presentations or verifiable presentations security: - networkAuth: [] - oAuth2: [] - zCap: [] operationId: getPresentations x-expectedCaller: - Holder Coordinator - Workflow Service x-componentTableLink: "get-presentations" parameters: - in: query name: type schema: type: array items: type: string pattern: "(presentations|verifiablepresentations|all)" responses: "200": description: Presentations retrieved content: application/json: schema: type: array description: The Presentations items: anyOf: - $ref: "./components/Presentation.yml#/components/schemas/Presentation" - $ref: "./components/VerifiablePresentation.yml#/components/schemas/VerifiablePresentation" "400": description: Bad Request "401": description: Not Authorized "410": description: Gone! There is no data here post: summary: Creates a presentation and returns it in the response body. tags: - Presentations security: - networkAuth: [] - oAuth2: [] - zCap: [] operationId: createPresentation x-expectedCaller: - Holder Coordinator - Workflow Service x-componentTableLink: "create-presentation" description: Creates a presentation and returns it in the response body. requestBody: content: application/json: schema: $ref: "#/components/schemas/CreatePresentationRequest" description: Parameters for creating the presentation. responses: "201": description: Presentation successfully created! content: application/json: schema: $ref: "#/components/schemas/CreatePresentationResponse" "400": description: invalid input! /callbacks/{localCallbackId}: post: summary: A callback that can be any capability URL (i.e., a URL that is infeasible to guess) that can be notified when an exchange step is performed. The URL SHOULD be a capability URL to ensure that it can only be used by parties with whom the URL is shared without a need for authorization tokens, periodic token refresh, nor client registration. If the suggested URL format with "localCallbackId" is used, then the "localCallbackId" value must express at least 128-bits of random information in order to ensure the full callback URL can be treated as a capability URL. It is also recommended that a new capability URL be created per exchange and only used by that exchange. tags: - Exchanges security: - networkAuth: [] - oAuth2: [] - zCap: [] operationId: callback x-expectedCaller: Workflow Service x-componentTableLink: "exchange-step-callbacks" parameters: - $ref: "./components/parameters/path/LocalCallbackId.yml" description: A system can expose this endpoint to be notified when an exchange step is executed. A request that the server cannot understand results in an error. requestBody: description: Information related to exchange that initiated the callback. content: application/json: schema: $ref: "#/components/schemas/CallbackData" responses: "200": description: Callback data received. "400": description: Callback data was not received. /credentials/verify: post: summary: Verifies a verifiableCredential and returns a verificationResult in the response body. tags: - Credentials security: - networkAuth: [] - oAuth2: [] - zCap: [] operationId: verifyCredential x-expectedCaller: - Verifier Coordinator - Workflow Service x-componentTableLink: "verify-credential" description: Verifies a verifiableCredential and returns a verificationResult in the response body. requestBody: content: application/json: schema: oneOf: - $ref: "#/components/schemas/VerifyCredentialRequest" - $ref: "#/components/schemas/VerifyEnvelopedCredentialRequest" description: Parameters for verifying a verifiableCredential. responses: "200": description: Verifiable Credential successfully verified! content: application/json: schema: $ref: "#/components/schemas/VerifyCredentialResponse" "400": description: invalid input! /presentations/verify: post: summary: Verifies a Presentation and all Verifiable Credentials it contains, returning detailed verification results. tags: - Presentations security: - networkAuth: [] - oAuth2: [] - zCap: [] operationId: verifyPresentation x-expectedCaller: - Verifier Coordinator - Workflow Service x-componentTableLink: "verify-presentation" description: | Verifies a verifiablePresentation and, by default, all verifiable credentials contained within it. The verification process includes verifying the presentation's own proof (including domain and challenge validation, if provided); verifying each contained verifiable credential's proof, status, and validity period(s); and 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) is outside the scope of this verification endpoint and should be performed by the calling application. The API is compositional: when credential verification is disabled or limited via implementation-specific options, individual credentials can be verified separately using the /credentials/verify endpoint. Given the possibility of denial of service, buffer overflow, or other attacks, an implementation is permitted to apply rate limits or otherwise restrict requests against this API endpoint as needed, using a 413, 429, or other response error code as appropriate. requestBody: content: application/json: schema: oneOf: - $ref: "#/components/schemas/VerifyPresentationRequest" - $ref: "#/components/schemas/ProoflessVerifyPresentationRequest" - $ref: "#/components/schemas/VerifyEnvelopedPresentationRequest" description: Parameters for verifying a verifiablePresentation. responses: "200": description: | Verification process completed successfully. The response body contains detailed results indicating whether the presentation and its contained credentials passed or failed verification. A 200 status indicates the verification process itself succeeded, regardless of whether the presentation and/or credentials were determined to be valid or invalid. content: application/json: schema: $ref: "#/components/schemas/VerifyPresentationResponse" "400": description: | 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": description: Payload too large "429": description: Request rate limit exceeded. /challenges: post: summary: Passing an empty body to this endpoint creates and returns a challenge string in the response body. security: - networkAuth: [] - oAuth2: [] - zCap: [] operationId: challenge x-expectedCaller: - Verifier Coordinator - Workflow Service x-componentTableLink: "create-challenge" description: Creates a challenge to be used as options.challenge in future requests. responses: "200": description: Challenge created content: application/json: schema: $ref: "#/components/schemas/CreateChallengeResponse" "400": description: Invalid or malformed input /interactions/{interactionId}: get: summary: Retrieve available interaction protocols from the interaction originator. tags: - Interactions - Credentials - Exchanges security: - networkAuth: [] - oAuth2: [] - zCap: [] operationId: startInteraction description: Retrieve available interaction protocols from the interaction originator. x-expectedCaller: Anyone with provided URL x-componentTableLink: "interaction-url-format" parameters: - in: path name: interactionId required: true schema: oneOf: - type: string - type: integer description: The unique interaction identifier for the current interaction. - in: query name: iuv required: true schema: type: string enum: ["1"] description: Informs a reader of the Interaction URL of the Interaction API version, and allows for quick disambiguation of the URL when scanned from a QR Code. requestBody: description: A request for the protocols object to negotiate an interaction protocol. content: application/json: schema: $ref: "#/components/schemas/Protocols" responses: "200": description: The protocols object with the advertised interaction protocol options. content: application/json: schema: $ref: "#/components/schemas/Protocols" "400": description: Invalid or malformed input "401": description: Not Authorized "500": description: Internal Error /{inviteId}/invite-request/response: post: summary: Provides a location for a particular invitation response to be submitted to the by the entity trying to start an interaction. When an implementer has implemented the full specification, it is expected that the {inviteId} parameter will be equivalent to the {exchangeId}. tags: - Interactions - Invite Request - Exchanges security: - networkAuth: [] - oAuth2: [] - zCap: [] operationId: receiveInvitationResponse description: Ths endpoint is one of the ones expected to be included as a fully formed URL in the protocols object returned by the /interactions/{interactionId} endpoint. x-expectedCaller: Whoever POSTed to the URL containing /interactions/{interactionId} x-componentTableLink: "interaction-protocols-response" parameters: - in: path name: inviteId required: true schema: oneOf: - type: string - type: integer description: The unique inviteId that the interaction requester uses to select the invite response protocol from the set of advertised options. When an implementer has implemented the full specification, this value will be an {exchangeId}, and that the invite-request/response endpoint lives on the Workflow Service. requestBody: description: The inviteResponse object provides a URL to continue the interaction, a purpose for the interaction, and an ID to reference the interaction by (mostly for debug purposes). content: application/json: schema: $ref: "#/components/schemas/InviteResponse" responses: "200": description: The inviteResponse object has been injested and was understood. This does not mean an interaction will continue, only that the inviteResponse was understood. "400": description: Invalid or malformed input. components: securitySchemes: $ref: "./components/SecuritySchemes.yml#/components/securitySchemes" schemas: UpdateCredentialStatusRequest: type: object required: ['credentialId', 'credentialStatus', 'status'] additionalProperties: false description: Credential status information to be updated. properties: credentialId: type: string description: Identifies the credential (the identifier does not have to appear in the VC itself). credentialStatus: type: object description: Identifies the specific status list entry to update. required: ['type', 'statusPurpose'] additionalProperties: false properties: id: type: string type: type: string statusPurpose: type: string statusListIndex: type: string statusListCredential: type: string status: type: boolean description: Specifies the new status. indexAllocator: type: string description: For services to use which indexes are being used/assigned to VCs. example: { "credentialId": "0fc754bc-fc32-46a0-aec1-a5ef385e7ea0", "credentialStatus": { "type": "BitstringStatusList", "statusPurpose": "revocation" }, "status": True } CreateStatusListRequest: type: object required: ['statusPurpose'] additionalProperties: false description: Parameters for creating a new status list credential. properties: statusPurpose: type: string description: The purpose of the status list (e.g., "revocation", "suspension"). This determines what type of status information the list will track. example: "revocation" id: type: string format: uri description: Optional identifier for the status list. If not provided, the service will generate one. options: type: object description: Optional parameters for creating the status list, such as size or other configuration options specific to the status list mechanism being used. example: { "statusPurpose": "revocation", "id": "https://issuer.example.com/credentials/status/lists/abc123" } CreateStatusListResponse: type: object properties: verifiableCredential: $ref: "./components/VerifiableCredential.yml#/components/schemas/VerifiableCredential" id: type: string format: uri description: The identifier of the created status list credential, which can be used to retrieve it via the GET endpoint. example: { "id": "https://issuer.example.com/credentials/status/lists/abc123", "verifiableCredential": { "@context": [ "https://www.w3.org/ns/credentials/v2" ], "id": "https://issuer.example.com/credentials/status/lists/abc123", "type": ["VerifiableCredential", "BitstringStatusListCredential"], "issuer": "did:example:issuer", "validFrom": "2024-01-01T00:00:00Z", "credentialSubject": { "id": "https://issuer.example.com/credentials/status/lists/abc123#list", "type": "BitstringStatusList", "statusPurpose": "revocation", "encodedList": "H4sIAAAAAAAAA-3BMQEAAADCoPVPbQwfoAAAAACAP2A1AQAAZQAAAIA..." }, "proof": { "type": "DataIntegrityProof", "cryptosuite": "eddsa-rdfc-2022", "verificationMethod": "did:example:issuer#key-1", "created": "2024-01-01T00:00:00Z", "proofPurpose": "assertionMethod", "proofValue": "z..." } } } IssueCredentialRequest: type: object properties: credential: $ref: "./components/Credential.yml#/components/schemas/Credential" options: $ref: "./components/IssueCredentialOptions.yml#/components/schemas/IssueCredentialOptions" IssueCredentialResponse: type: object properties: IssueCredentialResponse: $ref: "./components/VerifiableCredentialResponse.yml#/components/schemas/VerifiableCredentialResponse" CreateWorkflowRequest: type: object additionalProperties: false description: Object containing information for creating a workflow. properties: id: type: string description: The ID that will be used for the created workflow. Passing an ID is OPTIONAL. initialStep: type: string description: The step from the above set that the exchange starts on. Passing initialStep is REQUIRED. controller: type: string description: 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: type: object description: An OPTIONAL property that specifies authorization scheme information for the endpoint, such as an OAuth2 configuration. properties: oauth2: type: object description: OAuth2 configuration. properties: issuerConfigUrl: type: string description: OAuth2 issuer config URL. credentialTemplates: type: array description: One or more templates for credential issuance. The template string should render to an object containing a credential field, which holds the credential template, and (optionally) an options field, which holds important credential issuing parameters (this is the format of the request body that is sent to POST /credentials/issue). Passing credentialTemplates is OPTIONAL. items: type: object properties: id: type: string description: The ID of the template. type: type: string description: The type of template. # Other options are possible enum: - "jsonata" template: type: string description: The template itself. steps: type: object description: 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. properties: STEP_NAME: $ref: "#/components/schemas/WorkflowStep" GetWorkflowResponse: type: object additionalProperties: false description: Object containing information about a workflow. properties: id: type: string description: The ID that will be used for the created workflow. Passing an ID is OPTIONAL. initialStep: type: string description: The step from the above set that the exchange starts on. Passing intialStep is REQUIRED. controller: type: string description: The controller of the instance. Passing controller is OPTIONAL. authorization: type: object description: Authorization scheme information (e.g., OAuth2 configuration). Passing authorization is OPTIONAL. properties: oauth2: type: object description: OAuth2 configuration. properties: issuerConfigUrl: type: string description: OAuth2 issuer config URL. credentialTemplates: type: array description: One or more templates for credential issuance. The template string should render to an object containing a credential field, which holds the credential template, and (optionally) an options field, which holds important credential issuing parameters (this is the format of the request body that is sent to POST /credentials/issue). Passing credentialTemplates is OPTIONAL. items: type: object properties: type: type: string description: The type of template. template: type: string description: The template itself. steps: type: object description: 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. properties: STEP_NAME: $ref: "#/components/schemas/WorkflowStep" CreateExchangeRequest: type: object description: Object containing information about the exchange to be created. properties: expires: type: string description: The date and time (expressed as an XML Schema dateTimeStamp) that the exchange expires. variables: $ref: "#/components/schemas/CreateExchangeVariables" openId: $ref: "#/components/schemas/OpenIdExchangeConfig" ExchangeParticipationClientMessage: type: object description: A message from the client to the server during an exchange. oneOf: - type: object description: An empty object to initiate the exchange or request what the exchange is expecting to complete the next step. properties: {} additionalProperties: false - type: object required: - verifiablePresentationRequest properties: verifiablePresentationRequest: $ref: "./components/VerifiablePresentationRequest.yml#/components/schemas/VerifiablePresentationRequest" referenceId: type: string description: When the server previously sent a referenceId, the client SHOULD include it here to aid debugging and message correlation. The value SHOULD be a urn:uuid value. - type: object required: - verifiablePresentation properties: verifiablePresentation: $ref: "./components/VerifiablePresentation.yml#/components/schemas/VerifiablePresentation" referenceId: type: string description: When the server previously sent a referenceId, the client SHOULD include it here to aid debugging and message correlation. The value SHOULD be a urn:uuid value. - type: object required: - verifiablePresentation properties: verifiablePresentation: type: array description: The Verifiable Presentations that the client sends to the server. items: $ref: "./components/VerifiablePresentation.yml#/components/schemas/VerifiablePresentation" referenceId: type: string description: When the server previously sent a referenceId, the client SHOULD include it here to aid debugging and message correlation. The value SHOULD be a urn:uuid value. - type: object required: - redirectUrl properties: redirectUrl: type: string description: A client MAY send an interaction URL to the server as a redirectUrl, inviting the server to become the client for a different related exchange starting with that interaction URL. A server MAY engage with this redirectUrl. referenceId: type: string description: When the server previously sent a referenceId, the client SHOULD include it here to aid debugging and message correlation. The value SHOULD be a urn:uuid value. ExchangeParticipationServerMessage: type: object description: A message from the server to the client during an exchange. oneOf: - type: object description: An object empty of exchange continuation properties indicating the server wishes to terminate the exchange. properties: {} additionalProperties: false - type: object required: - verifiablePresentationRequest properties: verifiablePresentationRequest: $ref: "./components/VerifiablePresentationRequest.yml#/components/schemas/VerifiablePresentationRequest" referenceId: type: string description: An optional identifier to correlate exchange messages. A server MAY include this value; if present, the client SHOULD include it in its next message. The value SHOULD be a urn:uuid value. - type: object required: - verifiablePresentation properties: verifiablePresentation: $ref: "./components/VerifiablePresentation.yml#/components/schemas/VerifiablePresentation" referenceId: type: string description: An optional identifier to correlate exchange messages. A server MAY include this value; if present, the client SHOULD include it in its next message. The value SHOULD be a urn:uuid value. - type: object required: - verifiablePresentation properties: verifiablePresentation: type: array description: The Verifiable Presentations that the server sends to the client. items: $ref: "./components/VerifiablePresentation.yml#/components/schemas/VerifiablePresentation" referenceId: type: string description: An optional identifier to correlate exchange messages. A server MAY include this value; if present, the client SHOULD include it in its next message. The value SHOULD be a urn:uuid value. - type: object required: - redirectUrl properties: redirectUrl: type: string description: The URL the exchange wishes to redirect the client to. referenceId: type: string description: An optional identifier to correlate exchange messages. A server MAY include this value; if present, the client SHOULD include it in its next message. The value SHOULD be a urn:uuid value. GetExchangeProtocolsResponse: type: object additionalProperties: false description: Object containing information about the protocols that can be used to perform a specific exchange. properties: protocols: type: object description: An object containing one or more protocols that can be used to perform the specific exchange. properties: interact: type: string description: 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: type: string description: The URL to use when initiating a VCALM exchange. OID4VP: type: string description: The URL to use when initiating an OID4VP presentation. OID4VCI: type: string description: The URL to use when initiating an OID4VCI issuance. GetExchangeResponse: type: object additionalProperties: false description: Object containing information about an active exchange. This can be an empty object when a given exchange has no VP and no redirectUrl to send. properties: id: type: string description: The local exchange ID that identifies the exchange. sequence: type: integer description: A sequence number for the exchange. Set to 0 on creation. expires: type: string description: The date and time (expressed as an XML Schema dateTimeStamp) that the exchange expires. step: type: string description: The current step in the exchange. state: type: string description: The status ("pending" | "active" | "complete" | "invalid") of the exchange, set to "pending" on creation. lastError: $ref: "./components/ProblemDetails.yml#/components/schemas/ProblemDetails" variables: $ref: "#/components/schemas/GetExchangeVariables" WorkflowStep: type: object description: Object containing information about a workflow step. oneOf: - $ref: "#/components/schemas/StepData" - type: object properties: stepTemplate: $ref: "#/components/schemas/StepTemplate" StepTemplate: type: object additionalProperties: false description: A template for a workflow step. Either this must be present or the other step data must be present, but not both sets. properties: type: type: string description: The type of template. template: type: string description: The step template. CallbackData: type: object additionalProperties: false description: Information received by a callback URL as a part of an exchange step being executed. properties: event: type: object description: The event information associated with the callback. properties: data: type: object description: The event data associated with the callback. properties: exchangeId: type: string description: A URL to the exchange state that can be used to retrieve the current state of the exchange. StepData: type: object additionalProperties: false description: Step data to be included if a template is not used. properties: createChallenge: type: boolean description: An optional step directive that tells the exchange to handle challenge management via a VCALM verifier service it has a zcap for. verifiablePresentationRequest: $ref: "./components/VerifiablePresentationRequest.yml#/components/schemas/VerifiablePresentationRequest" verifiablePresentation: $ref: "./components/VerifiablePresentation.yml#/components/schemas/VerifiablePresentation" redirectUrl: type: string description: A URL to send to the client that can be used to continue an interaction at another location. Passing redirectUrl is OPTIONAL. callback: type: object description: A callback that will be called after this step executes. properties: url: type: string description: A URL that will receive the callback data. issueRequests: type: array items: type: object properties: credentialTemplateId: type: string description: The ID of the item in workflow.credentialTemplates that captures the schema of a credential that is issued in a step. credentialTemplateIndex: type: number description: The index of the item in workflow.credentialTemplates that captures the schema of a credential that is issued in a step. # Optionally specify different variables from exchange.variables # (either a string that is the name of a variable in exchange.variables # to use, or a whole object with alternative variables) variables: oneOf: - type: string - $ref: "#/components/schemas/CreateExchangeVariables" result: type: string description: If present, identifies where the result of the issue request is to be stored. The value MUST be either the name of a top-level variable in the exchange's variables object or a JSON pointer to any variable within the exchange's variables object. oneOf: - required: - credentialTemplateId - required: - credentialTemplateIndex additionalProperties: false presentationSchema: oneOf: - type: object description: A JSON Schema describing the validation to be performed on the presentation. properties: type: type: string description: The value MUST be JsonSchema. jsonSchema: type: object description: The JSON Schema object to use when validating the presentation. - type: object description: 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. properties: type: type: string description: The type of presentation schema mechanism to use when validating the presentation. verifyPresentationResponseSchema: oneOf: - type: object description: A JSON Schema describing the validation to be performed on the result of verifying the presentation. properties: type: type: string description: The value MUST be JsonSchema. jsonSchema: type: object description: The JSON Schema object to use when validating the result of verifying the presentation. - type: object description: 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. properties: type: type: string description: The type of presentation schema mechanism to use when validating the result of verifying the presentation. nextStep: type: string description: 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: $ref: "#/components/schemas/OpenIdExchangeConfig" CreateExchangeVariables: type: object description: Variables needed for creating an exchange. GetExchangeVariables: type: object description: Variables needed for an exchange. properties: results: type: object description: Results from each step of an exchange. properties: STEP_NAME: $ref: "#/components/schemas/ExchangeStepResults" ExchangeStepResults: type: object description: Results from a step of an exchange. properties: verifiablePresentation: $ref: "./components/VerifiablePresentation.yml#/components/schemas/VerifiablePresentation" openId: type: object description: Results from OID4VCI/OID4VP holder interaction. properties: clientProfileId: type: object description: The identifier for the particular profile of OID4VCI/OID4VP chosen to be used from the openId.clientProfiles object in the exchange step configuration. A single exchange can offer multiple profiles for an exchange client (e.g., a digital wallet) to use; this identifier signals to the coordinator which was selected. authorizationResponse: type: object description: A credential bearing response that the holder sends to the issuer or verifier. presentationSubmission: type: object description: A mapping between input descriptors and credentials that a holder submits. inviteRequest: type: object description: Results from an invite request. properties: inviteResponse: type: object description: Response to invite request indicating where to redirect holder. properties: url: type: string description: URL where exchange should proceed. purpose: type: string description: Description of interaction. referenceId: type: string description: Unique ID of invite request. DeriveCredentialRequest: type: object properties: verifiableCredential: $ref: "./components/VerifiableCredential.yml#/components/schemas/VerifiableCredential" options: $ref: "./components/DeriveCredentialOptions.yml#/components/schemas/DeriveCredentialOptions" DeriveCredentialResponse: $ref: "./components/VerifiableCredential.yml#/components/schemas/VerifiableCredential" CreatePresentationRequest: type: object properties: presentation: $ref: "./components/Presentation.yml#/components/schemas/Presentation" options: $ref: "./components/PresentCredentialOptions.yml#/components/schemas/PresentCredentialOptions" CreatePresentationResponse: type: object properties: verifiablePresentation: type: object description: A JSON-LD Verifiable Presentation with a proof. oneOf: - $ref: "./components/VerifiablePresentation.yml#/components/schemas/VerifiablePresentation" - $ref: "./components/EnvelopedVerifiablePresentation.yml#/components/schemas/EnvelopedVerifiablePresentation" StorePresentationRequest: $ref: "./components/VerifiablePresentation.yml#/components/schemas/VerifiablePresentation" VerifyCredentialRequest: type: object properties: verifiableCredential: $ref: "./components/VerifiableCredential.yml#/components/schemas/VerifiableCredential" options: $ref: "./components/VerifyCredentialOptions.yml#/components/schemas/VerifyCredentialOptions" VerifyEnvelopedCredentialRequest: type: object properties: verifiableCredential: $ref: "./components/EnvelopedVerifiableCredential.yml#/components/schemas/EnvelopedVerifiableCredential" options: $ref: "./components/VerifyCredentialOptions.yml#/components/schemas/VerifyCredentialOptions" VerifyCredentialResponse: $ref: "./components/VerifyCredentialResult.yml#/components/schemas/VerificationResult" VerifyPresentationRequest: type: object properties: verifiablePresentation: $ref: "./components/VerifiablePresentation.yml#/components/schemas/VerifiablePresentation" options: $ref: "./components/VerifyPresentationOptions.yml#/components/schemas/VerifyPresentationOptions" VerifyEnvelopedPresentationRequest: type: object properties: verifiablePresentation: $ref: "./components/EnvelopedVerifiablePresentation.yml#/components/schemas/EnvelopedVerifiablePresentation" options: $ref: "./components/VerifyPresentationOptions.yml#/components/schemas/VerifyPresentationOptions" ProoflessVerifyPresentationRequest: type: object properties: presentation: $ref: "./components/Presentation.yml#/components/schemas/Presentation" VerifyPresentationResponse: $ref: "./components/VerifyPresentationResult.yml#/components/schemas/VerificationResult" CreateChallengeResponse: $ref: "./components/Challenge.yml#/components/schemas/CreateChallengeResult" Protocols: type: object description: Object containing the available options for continuing the current interaction. properties: inviteRequest: type: string description: A URL that is intended to take the initiating user of the current interaction to a website to continue the interaction beyond this API. example: https://website.example/invitation/87654321/invite-request/response vcapi: type: string description: A VC-API exchange URL that will allow the initiating user of the current interaction to continue with a VC-API credential exchange. example: https://vcapi.example/workflows/z1A1FjMfnG/exchanges/z19mxakBFecZ otherFutureAPI: type: string description: A URL that is intended to take the initiating user of the current interaction to some other, as yet to be defined, API to continue the interaction and credential exchange. example: https://otherFutureAPI.example/collection/0987 oneOf: - required: - inviteRequest - required: - vcapi InviteResponse: type: object description: Object for a continuation URL for an interaction, along with a purpose for a given interaction. required: - url - purpose - referenceId properties: url: type: string description: A URL where the recipient can continue the interaction, should they choose. example: https://website.example/checkout/8372974 purpose: type: string description: A reason for the interaction that is human readable and usable in a concent interaction with the user recieving the inviteResponse object. example: "Checkout at ShopCo" referenceId: type: string description: An ID used to reference this particular inviteResponse, mostly for debug purposes. example: 417bcaf2-14d9-11f0-99d7-9f094678517b OpenIDClientProfile: type: object additionalProperties: false description: Client profile configuration for exchanges using OID4VCI/OID4VP. properties: createAuthorizationRequest: type: string description: If present, identifies where the auto-generated OID4VP authorization request will be stored for subsequent use in the exchange. The value MUST be either the name of a top-level variable in the exchange's variables object (see Create Exchange) or a JSON pointer to any variable within the exchange's variables object. 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: type: object description: If present, an OID4VP authorization request for subsequent use in the exchange. Either this or createAuthorizationRequest MUST be present, but not both. # The following are optional properties that can be used as overrides in any authorization request: # ==================================================================================================== client_id: type: string description: The identifier of the OID4VP client. This is defined in RFC 6749 as the application making protected resource requests on behalf of the resource owner using its authorization. In OID4VP, the client acts on behalf of the party making a request for a verifiable presentation; for example, a server that is interacting with a digital wallet. client_id_scheme: type: string description: The scheme of the identifier of the OID4VP client. This is defined in OID4VP draft 18, but was removed in OID4VP 1.0. It is made available for backwards compatibility purposes with the popular OID4VP draft 18. client_metadata: type: object description: Important metadata about the OID4VP client to use in an exchange (defined in RFC 7591). nonce: type: string description: A single-use value created by the OID4VP client to prevent replay attacks during an exchange (defined in OIDC 1.0). dcql_query: type: object description: A Digital Credentials Query Language (DCQL) JSON object that specifies which credentials the OID4VP client requests during an exchange. DCQL is defined in draft 22 of OID4VP as a more advanced alternative to DIF Presentation Exchange. presentation_definition: type: object description: A Presentation Exchange (PE) JSON object that specifies which credentials the OID4VP client requests during an exchange. PE is defined in DIF Presentation Exchange 1.0.0 and used in OID4VP 1.0, but since draft 22, it has been been phased out in favor of DCQL. response_mode: type: string description: A directive from an OID4VP client instructing how to submit an authorization response during an exchange (defined in OIDC 1.0). response_uri: type: string description: A directive from an OID4VP client instructing where to submit an authorization response during an exchange; works in tandem with response_mode=direct_post (defined in OID4VP 1.0). redirect_uri: type: string description: A URI specified by the OID4VP client to indicate where to redirect UX control after an exchange (defined in RFC 6749). # ==================================================================================================== authorizationRequestSigningParameters: type: object additionalProperties: false description: Parameters needed for signing authorization requests submitted via OID4VP during an exchange. properties: x5c: type: array items: type: string required: - x5c protocolUrlParameters: type: object additionalProperties: false description: OID4VCI/OID4VP URL parameters. properties: name: type: string description: Name used in OID4VCI/OID4VP URL scheme: type: string description: Scheme used in OID4VCI/OID4VP URL required: - name - scheme zcapReferenceIds: type: object additionalProperties: false description: References to ZCAPs needed during an exchange that is using OID4VCI/OID4VP. properties: signAuthorizationRequest: type: string description: Reference to a ZCAP needed for signing an authorization request submitted during an exchange using OID4VP. required: - signAuthorizationRequest oneOf: # An authorization request or a directive to create one can be used, # but not both - required: - createAuthorizationRequest not: required: - authorizationRequest - required: - authorizationRequest not: required: - createAuthorizationRequest OpenIdExchangeConfig: type: object additionalProperties: false description: Optional parameters to enable OID4VCI/OID4VP protocols for credential delivery/presentation. oneOf: - $ref: "#/components/schemas/OpenIDClientProfile" - type: object properties: clientProfiles: type: object additionalProperties: $ref: "#/components/schemas/OpenIDClientProfile"