---
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 initialStep 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 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.
    - `id` string — The ID of the template.
    - `type` 'jsonata' — 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` WorkflowStep — unresolved $ref

## Response `201`

Workflow successfully created (with data)

## Other responses

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

## Changes

- **2026-04-07** `84fcdb545382` — 1 info
  - added the new optional request property `steps/STEP_NAME/oneOf[#/components/schemas/StepData]/redirectUrl`
- **2026-03-31** `041dd184897c` — 1 info
  - added the new optional request property `steps/STEP_NAME/oneOf[#/components/schemas/StepData]/issueRequests/items/result`
- **2026-03-26** `231035da3956` — 1 info
  - added the new optional request property `steps/STEP_NAME/oneOf[#/components/schemas/StepData]/verifiablePresentation`
- **2026-03-10** `06a69b7adc39` — 1 breaking, 1 info
  - removed `#/components/schemas/GetExchangeVariables` from the `steps/STEP_NAME/oneOf[#/components/schemas/StepData]/issueRequests/items/variables` request property `oneOf` list
  - added `#/components/schemas/CreateExchangeVariables` to the `steps/STEP_NAME/oneOf[#/components/schemas/StepData]/issueRequests/items/variables` request property `oneOf` list
- **2026-03-10** `848345580ee6` — 1 breaking, 1 info
  - removed `#/components/schemas/ExchangeVariables` from the `steps/STEP_NAME/oneOf[#/components/schemas/StepData]/issueRequests/items/variables` request property `oneOf` list
  - added `#/components/schemas/GetExchangeVariables` to the `steps/STEP_NAME/oneOf[#/components/schemas/StepData]/issueRequests/items/variables` request property `oneOf` list

[Full history](https://skmtc.dev/w3c/apis/verifiable-credential-api-for-lifecycle-management/changes/workflows/post.md)

---

[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/84fcdb545382/schema)