diff --git a/components/parameters/path/LocalExchangeId.yml b/components/parameters/path/LocalExchangeId.yml new file mode 100644 index 0000000..7659238 --- /dev/null +++ b/components/parameters/path/LocalExchangeId.yml @@ -0,0 +1,7 @@ +name: localExchangeId +description: A local identifier for an exchange instance. +in: path +required: true +schema: + type: string + pattern: "[a-z0-9][a-z0-9\\-]{2,}" \ No newline at end of file diff --git a/components/parameters/path/LocalWorkflowId.yml b/components/parameters/path/LocalWorkflowId.yml new file mode 100644 index 0000000..1ddfd04 --- /dev/null +++ b/components/parameters/path/LocalWorkflowId.yml @@ -0,0 +1,7 @@ +name: localWorkflowId +description: A local identifier for a workflow instance. +in: path +required: true +schema: + type: string + pattern: "[a-z0-9][a-z0-9\\-]{2,}" \ No newline at end of file diff --git a/exchanges.html b/exchanges.html new file mode 100644 index 0000000..38e167a --- /dev/null +++ b/exchanges.html @@ -0,0 +1,20 @@ + + + + W3C CCG - VC Verifier API + + + + + + + + + + + \ No newline at end of file diff --git a/exchanges.yml b/exchanges.yml new file mode 100644 index 0000000..5c2ab26 --- /dev/null +++ b/exchanges.yml @@ -0,0 +1,397 @@ +openapi: 3.0.0 +servers: + - url: https://verifier.qa.veres.app/verifiers/z1A45ZhWEGMeibHrB15nv8Gk6 + description: Veres Verifier (Quality Assurance) +info: + version: "0.0.3-unstable" + title: VC Exchanges and Workflows API + description: This is an Experimental Open API Specification for the [VC Data Model](https://www.w3.org/TR/vc-data-model/). + 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-ccg/vc-api +paths: + /workflows: + post: + summary: Creates a new workflow and returns its information in the response body. + tags: + - Credentials + security: + - networkAuth: [] + - oAuth2: [] + - zCap: [] + operationId: createWorkflow + description: Creates a new workflow and returns workflowId in the response body. + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/CreateWorkflowRequest" + responses: + "200": + description: Workflow successfully created! + content: + application/json: + schema: + $ref: "#/components/schemas/CreateWorkflowResponse" + "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. + 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 exchangeId and time to live in the response body. + tags: + - Credentials + security: + - networkAuth: [] + - oAuth2: [] + - zCap: [] + operationId: createExchange + description: Creates a new exchange and returns exchangeId and time to live in the response body. + parameters: + - $ref: "./components/parameters/path/LocalWorkflowId.yml" + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/CreateExchangeRequest" + responses: + "200": + description: Exchange successfully created! + content: + application/json: + schema: + $ref: "#/components/schemas/CreateExchangeResponse" + "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. + 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. + 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. + parameters: + - $ref: "./components/parameters/path/LocalWorkflowId.yml" + - $ref: "./components/parameters/path/LocalExchangeId.yml" + requestBody: + content: + application/json: + schema: + properties: + verifiablePresentation: + $ref: "./components/VerifiablePresentation.yml#/components/schemas/VerifiablePresentation" + responses: + "200": + description: Exchange progressed. + content: + application/json: + schema: + $ref: "#/components/schemas/ExchangeParticipationResponse" + "400": + description: Invalid input + "401": + description: Not Authorized + "500": + description: Internal Error +components: + securitySchemes: + $ref: "./components/SecuritySchemes.yml#/components/securitySchemes" + schemas: + CreateWorkflowRequest: + type: object + additionalProperties: false + description: Object containing information for creating a workflow. + properties: + workflowData: + type: object + additionalProperties: false + description: Object containing information for creating a workflow. + properties: + steps: + type: object + description: One or more steps required to complete an exchange on the workflow. Passing the steps object is REQUIRED. + properties: + stepName: + type: object + description: The name of the step. + properties: + step: + $ref: "#/components/schemas/WorkflowStep" + 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: string + description: Authorization scheme information (e.g., OAuth2 configuration). Passing authorization is OPTIONAL. + credentialTemplates: + type: array + description: One or more VC templates for issuance. Passing credentialTemplates is OPTIONAL. + items: + type: object + properties: + type: + type: string + template: + type: string + workflowId: + type: string + description: the ID that will be used for the created workflow. workflowId is OPTIONAL. + CreateWorkflowResponse: + type: object + additionalProperties: false + description: Object containing information about a created workflow. + properties: + workflowId: + type: string + description: The URL that uniquely identifies the created workflow. + GetWorkflowResponse: + type: object + additionalProperties: false + description: Object containing information about a workflow. + properties: + workflowData: + type: object + additionalProperties: false + description: Object containing information about a created workflow. + properties: + stepInformation: + type: object + description: Information about the steps required for the workflow. Returning stepInformation is REQUIRED. + properties: + exchanges: + type: array + description: The identifiers of the current exchanges associated with the workflow instance. + items: + type: string + steps: + type: object + description: One or more steps required to complete an exchange on the workflow. + properties: + stepName: + type: object + description: The name of the step. + properties: + step: + $ref: "#/components/schemas/WorkflowStep" + initialStep: + type: string + description: The step from the above set that the exchange starts on. + controller: + type: string + description: The controller of the instance. Returning controller is OPTIONAL. + authorization: + type: object + description: Authorization scheme information (e.g., OAuth2 configuration). Returning authorization is OPTIONAL. + credentialTemplates: + type: array + description: One or more VC templates for issuance. Returning credentialTemplates is OPTIONAL. + items: + type: object + properties: + type: + type: string + description: The type of template. + template: + type: string + description: The template itself. + CreateExchangeRequest: + type: object + description: Object containing information about the exchange to be created. + properties: + exchangeInformation: + type: object + properties: + ttl: + type: string + description: Time to live for the exchange (ms). + variables: + type: array + description: Template variables to be used in the exchange. + items: + type: object + properties: + type: + type: string + description: The type of template. + template: + type: string + description: The template itself. + CreateExchangeResponse: + type: object + additionalProperties: false + description: Object containing information about a created exchange. + properties: + exchangeId: + type: string + description: The URL that uniquely identifies the exchange. + sequence: + type: string + description: A sequence number for the exchange. Set to "0" on creation. + ttl: + type: string + description: The time to live for the created exchange. + variables: + type: array + description: Template variables to be used in the exchange. + items: + type: object + properties: + type: + type: string + description: The type of template. + template: + type: string + description: The template itself. + state: + type: string + description: The status ("pending" | "complete" | "invalid") of the exchange, set to "pending" on creation. + step: + type: string + description: The semantic string ID for the current step. + ExchangeParticipationResponse: + type: object + description: Either what the exchange is expecting next or a result of the exchange. + oneOf: + - type: object + properties: + verifiablePresentationRequest: + $ref: "./components/VerifiablePresentationRequest.yml#/components/schemas/VerifiablePresentationRequest" + - type: object + properties: + verifiablePresentation: + $ref: "./components/VerifiablePresentation.yml#/components/schemas/VerifiablePresentation" + - type: object + properties: + redirectUrl: + type: string + description: The URL the exchange wishes to redirect the client to. + GetExchangeResponse: + type: object + additionalProperties: false + description: Object containing information about an active exchange. + properties: + exchangeId: + type: string + description: The URL that uniquely identifies the exchange. + ttl: + type: string + description: The time to live for the exchange. + nextStep: + type: string + description: The interaction the exchange is expecting to happen next. + completedSteps: + type: array + description: The steps completed by the exchange previously. + items: + type: string + 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. + StepData: + type: object + additionalProperties: false + description: Step data to be included if a template is not used. + properties: + createChallenge: + type: string + description: An optional step directive that tells the exchange to handle challenge management via a VC API verifier service it has a zcap for. + verifiablePresentationRequest: + $ref: "./components/VerifiablePresentationRequest.yml#/components/schemas/VerifiablePresentationRequest" + nextStep: + type: string + description: The name of the next step in the sequence. + openId: + type: object + description: Optional information to trigger OID4VP + properties: + createAuthorizationRequest: + type: string + description: If present, auto-generate the OID4VP authorization request from the VPR. Either this or authorizationRequest must be present, but not both. + authorizationRequest: + type: object diff --git a/index.html b/index.html index c49969a..9981327 100644 --- a/index.html +++ b/index.html @@ -831,6 +831,62 @@

Create Challenge

+
+

Workflows and Exchanges

+

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

+ +
+ +
+

Create Workflow

+

+

+ +
+
+ +
+

Get Workflow Configuration

+

+

+ +
+
+ +
+

Create Exchange

+

+

+ +
+
+ +
+

Participate in an Exchange

+

+

+ +
+
+ +
+

Get Exchange State

+

+

+ +
+
+ +
+

Presenting

diff --git a/respec-oas.js b/respec-oas.js index 9a98b79..60438c5 100644 --- a/respec-oas.js +++ b/respec-oas.js @@ -360,13 +360,16 @@ async function injectOas(config, document) { const issuerApi = await SwaggerParser.validate('issuer.yml'); console.log('API name: %s, Version: %s', issuerApi.info.title, issuerApi.info.version); + const exchangesApi = await SwaggerParser.validate('exchanges.yml'); + console.log('API name: %s, Version: %s', + exchangesApi.info.title, exchangesApi.info.version); const verifierApi = await SwaggerParser.validate('verifier.yml'); console.log('API name: %s, Version: %s', verifierApi.info.title, verifierApi.info.version); const holderApi = await SwaggerParser.validate('holder.yml'); console.log('API name: %s, Version: %s', holderApi.info.title, holderApi.info.version); - const apis = [issuerApi, verifierApi, holderApi]; + const apis = [issuerApi, verifierApi, holderApi, exchangesApi]; buildApiSummaryTables({config, document, apis}); buildEndpointDetails({config, document, apis});