Skip to content

API Gateway: Expose Workflows as APIs

Endpoints are defined as routes within a service. Each route is linked to a Conductor workflow. When a request is made to the route, Conductor executes the associated workflow and returns its output as the response. To secure access, you can configure authentication settings that define how clients are authorized to invoke each route.

Here’s an overview of how to expose workflows as APIs in Conductor:

  1. Create workflows to define the logic for each endpoint.
  2. Create an application with permission to execute the workflows. This acts as the service account layer.
  3. Configure authentication settings for the API service.
  4. Define an API service.
  5. Define and test routes.

5-minute path

Create the workflow, create an application with Execute permission on it, configure authentication, define a service with a base path and auth config, then add a route mapped to the workflow and test it.

Step 1: Create workflows to define the logic for each endpoint

API Gateway exposes workflows as APIs. Before configuring the endpoints, create the required workflows for each endpoint’s logic.

You can create workflows using Conductor UI, APIs, or SDKs.

Step 2: Create an application in Orkes Conductor

Applications in Orkes Conductor act as the service account layer that interacts with the Conductor server. Through this application, you assign the permissions required to execute workflows exposed as APIs.

To create an application:

  1. Go to Access Control > Applications, and select + Create application.
  2. Enter a name for the application.
  3. (Optional) Enable the required Application role based on how the service wants to interact with the application.
  4. In Permissions, select + Add permission.

  5. In the Workflow tab, select the workflow created in Step 1 and enable EXECUTE permission.

  6. Save the application.

The next step is to create an authentication setting for the API service.

Step 3: Configure authentication settings

Authentication settings control how clients are authorized to access a service. You can create authentication settings globally in your Conductor cluster and reuse them across services.

To configure authentication settings:

  1. Go to APIs > Authentication from the left navigation menu on your Conductor cluster.
  2. Select + New authentication.
  3. Configure the following parameters:
Parameter Description Required/Optional
ID A unique identifier for the authentication configuration. This cannot be renamed once saved. Required.
Authentication Type The type of authentication to use. Supported values:
  • API Key–Enforces basic authentication using an API key.
  • No Authentication–No authentication is enforced, and the API will be accessible to anyone.
 Required.
API Key The API key for authentication. A random key is generated by default. You can also select Generate to create one instantly. Copy and store the key securely for future authentication. Required if Authentication Type is API Key.
Application Select the application created in Step 2, which generates an access key and JWT token. The API Gateway will use this token to authenticate with the Conductor. The service using this authentication will inherit the application’s permissions. Required.
  1. Select Save.

Step 4: Define an API service

A service represents a logical grouping of API endpoints (called routes) that share common settings such as base path, authentication, and CORS (Cross-Origin Resource Sharing) policies. Each route within a service maps to a specific workflow. You must create a service before adding individual routes.

To define a service:

  1. Go to APIs > Services from the left navigation menu on your Conductor cluster.
  2. Select + New service.
  3. Configure the following parameters:
Parameter Description Required/Optional
Basic information
Service ID A unique identifier for the service. Use lowercase letters and hyphens, as this value is used in the API URLs. This cannot be renamed once saved. Required.
Display Name A user-friendly name for the service. Required.
Service Enabled Determines whether the service is active. Enabled by default. Switch it off if you do not want to activate the service immediately. Required.
MCP Enabled Determines whether the MCP is active for this service. Enabled by default. Since this service is configured as an API gateway, this can be disabled. Required.
API Configuration
Base Path The base path for all routes in the service. The path must start with a forward slash (for example,` /api/v1/users`). Including `api` in the path is optional. This cannot be renamed once saved. Required.
Auth Config The authentication configuration to use for this service. Select the configuration created in the previous step, or select + Create New Auth Config from the dropdown, and configure the authentication settings. Required.
CORS Configuration
Allowed Origins The origins (URLs) that can access this service. Press Enter after each URL to add multiple origins. Use * to allow all origins. Required.
Allowed Methods The HTTP methods that can be used in cross-origin requests. Supported values:
  • GET
  • POST
  • PUT
  • DELETE
  • PATCH
  • OPTIONS
 Required.
Allowed Headers The HTTP headers that can be sent in requests from allowed origins. Press Enter after each header to add multiple headers. Use * to allow all headers. Required.
Additional Information
Description A description of the service. Optional.
  1. Select Save.

Step 5: Define and test a route

Each endpoint in a service must be defined as a route, which is mapped to the Conductor workflow that executes the logic.

To create a route within a service:

  1. Go to the Services and select the + button next to the service created.
  2. Configure the following parameters:
Parameter Description Required/Optional
Route Definition
HTTP Method The HTTP method for the route. Supported methods:
  • GET
  • POST
  • PUT
  • DELETE
  • PATCH
 Required.
Path The path for the request.
  • Must start with a forward slash. For example, `/update`.
  • Use {} for path parameters. For example, `/update/{userId}`.
 Required.
Description A description of the route. Optional.
Workflow Configuration
Workflow Name The workflow to be triggered by the route. Required.
Version The version of the workflow to use. If unspecified, the latest version will be used. Required.
Wait Until Tasks The task to wait for before returning a response. The API will return the output of this task, instead of the workflow output. This is useful if the workflow contains tasks that take a long time to complete, but a response from the API is required before the connection times out. Optional.
Timeout (seconds) The duration in seconds to wait before returning a response. Optional.
Schema
Input Schema The input schema for the request.
  • If you’ve created a schema in Conductor, select the schema and version to be used as the input schema for the request.
  • If not, enter your schema directly in the Code tab.
 Optional.
Output Schema The output schema for the request.
  • If you’ve created a schema in Conductor, select the schema and version to be used as the output schema for the request.
  • If not, enter your schema directly in the Code tab.
 Optional.
Query Parameters
Parameter Name The query parameter that can be accepted by the endpoint. Can contain only letters, numbers, underscores, and hyphens. Enable Required if the parameters are mandatory. Optional.
Transformation Scripts
Pre-request Script A JavaScript function to transform the incoming request payload before passing it to the workflow. The returned object becomes the workflow input. Use `$.fieldName` to access input fields. Example 
(function () {
return $.value1 + $.value2;
})();
Optional.
Test Pre-request Script Test the input processing script. To test the payload:
  1. In Test Payload, enter the values.
  2. Select Test Pre-request Script.
  3. In Test Result, verify the result to ensure the script is working.
 N/A
Post-response Script A JavaScript function to transform the final workflow output before it is returned in the API response. The returned object is sent as the API response. Use `$.fieldName` to access output fields. Example 
    (function () {
    return $.result * 2;
    })();
Optional.
Test Post-response Script Test the output processing script. To test the payload:
  1. In Test Payload, enter the values.
  2. Select Test Postresponse Script.
  3. In Test Result, verify the result to ensure the script is working.
 N/A
Cache Configuration
Cache Key Enables caching for a route. When caching is enabled, Conductor stores responses for repeated requests and returns the cached result for matching inputs until the entry expires. Optional.
TTL (Time To Live) in Seconds Set how long the cached value remains valid. Optional.
Rate Limit Configuration
Rate Limit Key Key used to identify the rate limit scope for this route. Can be [passed as a variable](/content/developer-guides/passing-inputs-to-task-in-conductor). Optional.
Concurrent Execution Limit Maximum number of concurrent executions allowed for this route. Optional.
  1. Select Save.

Test a route

You can test route behavior directly from the Conductor UI before exposing it as an API.

Run a test request

To test a route:

  1. Go to the APIs > Services, and select the service.
  2. In Routes, select the play icon next to the route to test.
  3. In Path Parameters, enter any required parameters for the endpoint.
  4. (If Authentication is using an API key) Replace *** with the API key copied in Step 3.
  5. In Body, enter the request payload as expected by the workflow.
  6. Select Test Route.
  7. Review the Response to verify the route works as expected.

Verify workflow execution

To confirm that the route triggered the workflow:

  1. Go to Executions > Workflow in your Conductor cluster and verify that the workflow is completed successfully.

  2. Select the Workflow ID to view the complete execution, including the workflow input and output.

View endpoint details

To get the cURL command:

  1. Go to APIs > Services, and select your service.
  2. Select a route to open its details.
  3. You can get the cURL command for the actual endpoint here.

To view the OpenAPI documentation for the endpoint:

  1. Go to APIs > Services, and select the service.
  2. In Metadata & Resources, select View API documentation.

Production notes

  • Restrict Allowed Origins to known domains instead of using *, since a permissive CORS policy lets any origin call the endpoint from a browser.
  • Use API Key authentication for production services. No Authentication makes the endpoint publicly callable by anyone with the URL.
  • Pin the route's Version once the API is in production, so a new workflow version doesn't silently change API behavior.
  • Set a Rate Limit Key and Concurrent Execution Limit on routes that handle high or unpredictable traffic to protect the underlying workflow from overload.
  • Re-test pre-request and post-response scripts and schemas after any change, since a malformed script or schema causes valid requests to fail.

Examples

See an example of a feedback service exposing a feedback workflow as a public API.

Monitor gateway metrics

Orkes Conductor's API and MCP Gateways provide built-in metrics at both service and route levels. These metrics help you monitor performance, identify usage trends, and troubleshoot issues in real time.

You can view metrics by selecting the Metrics tab from any service or route.

Performance metrics

Metric Description
Total Requests Total number of requests made to the service or route.
Request Rate Average number of requests per second.
Success Rate Percentage of successful workflow executions triggered by the service or route.
Avg Latency Average time (in milliseconds) taken to complete a request.

Statistics

The Statistics view provides detailed insights into request volume, latency patterns, and error trends for each service or route. Use this section to analyze performance behavior over time and identify issues that may need attention.

Requests

The Requests tab includes a line graph showing request volume over time. Use this view to monitor usage patterns, performance degradation, or abnormal error spikes across all routes in the service.

Latency

The Latency tab shows percentile-based response time distribution. Use this view to identify spikes or inconsistencies in performance.

  • P50 (median): Half the requests responded faster than this latency.
  • P95: 95% of requests completed faster than this latency.
  • P99: 99% of the requests are faster than this latency.

Errors

The Errors tab visualizes failure trends and error types.

  • Error Rate: Percentage of failed requests over time.
  • Error Breakdown: Types of errors returned (e.g., 400 Bad Request, 500 Internal Server Error) and their frequency.

Hover over the graph to inspect error events by timestamp. Use this to correlate API failures with recent deployments or configuration changes.