---
title: "Creates a new workflow and returns location of workflow metadata in a response header."
method: POST
path: "/workflows"
tags: ["Credentials"]
---

# Creates a new workflow and returns location of workflow metadata in a response header.

`POST /workflows`

Creates a new workflow and returns location of workflow metadata in a response header.

## Request body

- CreateWorkflowRequest — Object containing information for creating a workflow.
  - `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 <code>authorization</code> 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.
    - `oauth2` object — OAuth2 configuration.
      - `issuerConfigUrl` string — OAuth2 issuer config URL.
  - `credentialTemplates` object[] — One or more VC templates for issuance. Passing credentialTemplates is OPTIONAL.
    - `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 <code>request-employee-id</code>), and the values are step configurations.
    - `STEP_NAME` union — Object containing information about a workflow step.
      - object — Step data to be included if a template is not used.
        - `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` VerifiablePresentationRequest — unresolved $ref
        - `presentationSchema` union
          - object — A JSON Schema describing the validation to be performed on the presentation.
            - `type` string — The value MUST be <code>JsonSchema</code>.
            - `jsonSchema` object — The JSON Schema object to use when validating the presentation.
          - object — 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.
            - `type` string — The type of presentation schema mechanism to use when validating the presentation.
        - `verifyPresentationResponseSchema` union
          - object — A JSON Schema describing the validation to be performed on the result of verifying the presentation.
            - `type` string — The value MUST be <code>JsonSchema</code>.
            - `jsonSchema` object — The JSON Schema object to use when validating the result of verifying the presentation.
          - object — 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.
            - `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
          - `createAuthorizationRequest` string — If present, identifies the name of the template variable (in <code>variables</code> for an <a href="#create-exchange">exchange</a>) that the auto-generated OID4VP Authorization Request will be stored in for subsequent use in the exchange. Either this or <code>authorizationRequest</code> 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 — If present, an OID4VP Authorization Request for subsequent use in the exchange. Either this or <code>createAuthorizationRequest</code> MUST be present, but not both.
      - object
        - `stepTemplate` StepTemplate — A template for a workflow step. Either this must be present or the other step data must be present, but not both sets.
          - `type` string — The type of template.
          - `template` string — The step template.

## Response `201`

Workflow successfully created (with data)

## Other responses

- `204` — Workflow successfully created (without data)
- `400` — Invalid input
- `401` — Not Authorized
- `500` — Internal Error

---

[API](https://skmtc.dev/w3c/apis/verifiable-credential-api-for-lifecycle-management.md) · [All operations](https://skmtc.dev/w3c/apis/verifiable-credential-api-for-lifecycle-management/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/w3c/verifiable-credential-api-for-lifecycle-management/revisions/a52f8ca5b671/schema)