Product UpdatesStatus PageAutomation Institute
English
Get a trial

# Embedded API

WHO CAN USE THIS FEATURE?

A Embedded account is required to use Embedded Partner APIs. Contact your Workato representative for more info.

Workato's Embedded Partner Platform APIs enable partners to programmatically create and manage customers and assets, including recipes and connections.

# Base URL

The Embedded Partner APIs are a collection of endpoints for interacting with customers, recipes, and more. Each endpoint contains the base URL and the resource path to the object.

The base URL of the endpoint depends on the data center (opens new window) you use. Here are the base URLs for each of Workato's data centers:

US Data Center
https://www.workato.com/api/
EU Data Center
https://app.eu.workato.com/api/
JP Data Center
https://app.jp.workato.com/api/
SG Data Center
https://app.sg.workato.com/api/
AU Data Center
https://app.au.workato.com/api/

# Embedded APIs with Environments

The Embedded API enables you to provision Environments programmatically. The Embedded API structure also allows you to precisely target each environment (Development, Test, and Production) when using the Environments feature for your customers.

Refer to the Embedded APIs Environments for more information about provisioning the Environments feature.

# Access without Environments

The Embedded API allows you to interact with customers regardless of whether they have Environments provisioned. You must add the managed_user_id directly to the endpoint: /api/managed_users/:managed_user_id to interact with customers who do not have Environments provisioned.

# Targeted Environment access

The API enables targeted access to the Development, Test, and Production environments when interacting with customers who have Environments provisioned. Use the following endpoints based on your environment requirements:

  • Development: Access the development environment using /api/managed_users/:managed_user_id_dev
  • Test: Access the test environment using /api/managed_users/:managed_user_id_test
  • Production: Access the production environment using /api/managed_users/:managed_user_id_prod

Refer to the Embedded Environments APIs section in the Workato documentation for information on how to target the correct environment.

# Authentication

You must create an API Client to authenticate to the API. Learn more.

# Provide API tokens as a bearer token

Provide your API client's API token in the request headers as a bearer token.

curl -X GET 'https://www.workato.com/api/managed_users/19029/properties' \
      -H 'Authorization: Bearer <api_token>'

# Supported Formats

Requests sent to the API should include Content-type: application/json in the header:

curl  -X GET 'https://www.workato.com/api/managed_users/19029/properties?prefix=salesforce_sync.' \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \

Responses are encoded using application/json; charset=utf-8.

# HTTP response codes

# 200 Success

The 200 Success response indicates that the request was processed successfully by the server. The response body varies depending on the endpoint and operation performed, but it typically contains the requested data or a confirmation of the action performed.

# Sample reply

{
    "success": true
}

# 400 Bad Request

The 400 Bad Request error indicates that the server couldn't process the request due to client-side issues. Common causes include malformed requests, invalid fields, or violations of field constraints, such as unsupported data types.

# Sample reply

{
    "errors": [
        {
            "code": 400,
            "title": "No workspaces found matching the specified workspace filter conditions."
        }
    ]
}

# 401 Unauthorized

The 401 Unauthorized error is returned when the request lacks valid authentication credentials. Common causes include missing tokens, invalid tokens, or incorrect credentials.

# Sample reply

{
    "errors": [
        {
            "code": 401,
            "title": "Unauthorized"
        }
    ]
}

# 403 Forbidden

The 403 Forbidden error indicates that the client is authenticated but doesn't have the necessary permissions to access the requested resource.

# Sample reply

{
    "errors": [
        {
            "code": 403,
            "title": "Forbidden"
        }
    ]
}

# 404 Not Found

The 404 Not Found error is returned when the requested resource doesn't exist or can't be found. This can occur if the URL is incorrect or the resource has been deleted.

# Sample reply

{
    "errors": [
        {
            "code": 404,
            "title": "Not found"
        }
    ]
}

# 500 Server Error

The 500 Server Error code indicates that the server encountered an unexpected condition that prevented it from fulfilling the request. This error is usually caused by server-side issues.

# Sample reply

{
    "errors": [
        {
            "code": 500,
            "title": "Server error",
            "detail": "3188c2d0-29a4-4080-908e-582e7ed82580"
        }
    ]
}

# Resources

# API platform

Type Resource Description
GET /api/managed_users/:id/
api_collections		 List API collections in a customer workspace.
POST /api/managed_users/:id/
api_collections		 Create API collection in a customer workspace.
GET /api/managed_users/:id/
api_endpoints		 List API endpoints in a collection.
PUT /api/managed_users/:id/
api_endpoints/:id/enable		 Enable an API endpoint in a collection.
PUT /api/managed_users/:id/
api_endpoints/:id/disable		 Disable an API endpoint in a collection.
GET /api/managed_users/:id/
api_clients		 List API clients in a customer workspace. We recommend that you migrate to the List API clients (v2) endpoint to prepare for future deprecation.
GET /api/v2/managed_users/:id/
api_clients		 List all API clients in a customer workspace. Workato includes the project_id of the project to which the API client belongs in the response.
POST /api/managed_users/:id/
api_clients		 Create API client in a customer workspace. We recommend that you migrate to the Create API client (v2) endpoint to prepare for future deprecation.
POST /api/v2/managed_users/:id/
api_clients/api/v2/api_clients		 Create a new API client in a customer workspace within a project you specify.
GET /api/v2/managed_users/:id/
api_clients/:api_client_id		 Retrieve details of an API client by ID in a customer workspace.
PUT /api/v2/managed_users/:id/
api_clients/:api_client_id		 Update an existing API client within a project you specify in a customer workspace.
DELETE /api/v2/managed_users/:id/
api_clients/:api_client_id		 Delete an existing API client in a customer workspace.
GET /api/managed_users/:id/
api_access_profiles		 List access profiles belonging to an API client in a customer workspace. We recommend that you migrate to the List API keys endpoint to prepare for future deprecation.
GET /api/v2/managed_users/:id/
api_clients/:api_client_id/api_keys		 List API keys for an API client in a customer workspace.
POST /api/managed_users/:id/
api_access_profiles		 Create an access profile belonging to an API client in a customer workspace. We recommend that you migrate to the Create API key endpoint to prepare for future deprecation.
POST /api/v2/managed_users/:id/
api_clients/:api_client_id/api_keys		 Create an API key for an API client in a customer workspace.
PUT /api/managed_users/:id/
api_access_profiles		 Update an access profile belonging to an API client in a customer workspace. We recommend that you migrate to the Update API key endpoint to prepare for future deprecation.
PUT /api/v2/managed_users/:id/
api_clients/:api_client_id/api_keys/:api_key_id		 Update an API key for an API client in a customer workspace.
PUT /api/managed_users/:id/
api_access_profiles/:api_access_profile_id/enable		 Enable an access profile belonging to an API client in a customer workspace. We recommend that you migrate to the Enable API key endpoint to prepare for future deprecation.
PUT /api/v2/managed_users/:id/
api_clients/:api_client_id/api_keys/:api_key_id/enable		 Enable an API key for an API client in a customer workspace.
PUT /api/managed_users/:id/
api_access_profiles		 Disable an access profile belonging to an API client in a customer workspace. We recommend that you migrate to the Disable API key endpoint to prepare for future deprecation.
PUT /api/v2/managed_users/:id/
api_clients/:api_client_id/api_keys/:api_key_id/disable		 Disable an API key for an API client in a customer workspace.
PUT /api/managed_users/:id/
api_access_profiles/:id/refresh_secret		 Refreshes an access profile token or secret. We recommend that you migrate to the Refresh API key secret endpoint to prepare for future deprecation.
POST /api/v2/managed_users/:id/
api_clients/:api_client_id/api_keys/:api_key_id/refresh_secret		 Refresh the authentication token or OAuth 2.0 client secret for an API key in a customer workspace.
DELETE /api/v2/managed_users/:id/
api_clients/:api_client_id/api_keys/:api_key_id		 Delete an existing API key in a customer workspace.
GET /api/v2/managed_users/:id/
api_portals		 List all API portals associated with API clients in a customer workspace.

# Connections

Type Resource Description
GET /api/managed_users/:managed_user_id/
connections		 Returns a list of connections in a customer workspace.
POST /api/managed_users/:managed_user_id/
connections		 Allows the Embedded vendor to add a shell connection in a customer workspace.
PUT /api/managed_users/:managed_user_id/
connections/:connection_id		 Updates a connection in a customer workspace.
POST /api/managed_users/:managed_user_id/
connections/:connection_id/disconnect		 Disconnects a connection in a customer workspace.
DELETE /api/managed_users/:managed_user_id/
connections/:connection_id		 Deletes a connection in a customer workspace.

# Connectors

Type Resource Description
GET /api/integrations Query connector metadata.
GET /api/integrations/all Returns a paginated list of all connectors and associated metadata in an Embedded partner's account. The response includes standard and custom connectors.

# Custom connectors

Type Resource Description
GET /api/custom_connectors Get custom connectors.
GET /api/custom_connectors/:id Get custom connector by ID
POST /api/custom_connectors/:id/
oem_share/:version		 Create or update a shared connector
POST api/managed_users/:managed_user_id/
recipes/:recipe_id/share		 Share a recipe containing a custom connector with Embedded partners.
DELETE /api/custom_connectors/:id/
suppress_oem_version		 Remove a shared connector

# Custom OAuth profiles

Type Resource Description
POST /api/managed_users/:managed_user_id/
custom_oauth_profiles/:id/assign		 Assign a Custom OAuth profile to customer workspace
DELETE /api/managed_users/:managed_user_id/
custom_oauth_profiles/:id/unassign		 Unassigns a Custom OAuth profile to a customer workspace.

# Customer managers

Type Resource Description
GET /api/customer_managers List all customer managers.
PUT /api/customer_managers/:id Update a customer manager.
POST /api/customer_managers Create a new customer manager.
DELETE /api/customer_managers/:id Delete a customer manager.

# Customer workspace collaborators

Type Resource Description
POST /api/managed_users/:id/member_invitation Invites a collaborator to a managed customer workspace.

# Data retention

Type Resource Description
PUT /api/managed_users/:managed_user_id/update_data_retention Update a customer workspace's data retention period.

# Dynamic field mapping

Type Resource Description
GET /api/v2/managed_users/:managed_user_id
/recipes/:recipe_id/field_map_introspections		 List all field map introspections in a specific recipe.
GET /api/v2/managed_users/:managed_user_id
/recipes/:recipe_id/field_map_introspections/:id		 List the field map introspections for a specific field map schema.
PUT /api/v2/managed_users/:managed_user_id
/recipes/:recipe_id/field_map_introspections/:id		 Update field mapping for a specific field map schema.
POST /api/v2/managed_users/:managed_user_id
/recipes/:recipe_id/field_map_introspections/:id
/refresh_schema		 Refresh a recipe’s schema to update field map introspections.
POST /api/v2/managed_users/:managed_user_id
/recipes/:recipe_id/field_map_introspections/:id/pick_list		 Retrieve picklist values for specific fields within a field map introspection of a recipe.

# Environment management

Type Resource Description
GET /api/managed_users/:id/activity_logs Retrieves activity audit log records in a customer workspace.
GET /api/v2/managed_users/:id/tags Retrieves a list of tags in a customer workspace.
POST /api/v2/managed_users/:id/tags Creates a tag in a customer workspace.
PUT /api/v2/managed_users/:id/tags/:handle Updates a tag in a customer workspace.
DELETE /api/v2/managed_users/:id/tags/:handle Deletes a tag in a customer workspace.

# Environment properties

Type Resource Description
GET /api/managed_users/:managed_user_id/properties Returns a list of environment properties belonging to a customer workspace that matches a prefix.
POST /api/managed_users/:managed_user_id/properties Upserts environment properties to a customer workspace.

# Environments

Type Resource Description
POST /api/managed_users/:managed_user_id/:provision_environments Provisions Environments for an existing managed customer.

# Folders

Type Resource Description
GET /api/managed_users/:managed_user_id/folders List folders in a customer workspace.
POST /api/managed_users/:managed_user_id/folders Create a folder in a customer workspace.
PUT /api/managed_users/:managed_user_id/folders/:folder_id Update a folder in a customer workspace.
DELETE /api/managed_users/:managed_user_id/folders/:folder_id Delete a folder in a customer workspace.

# Jobs

Type Resource Description
GET /api/managed_users/:id/recipes/:recipe_id/jobs List jobs for a recipe.
GET /api/managed_users/:id/recipes/:recipe_id/jobs/:job_id Get job details.
Type Resource Description
PUT /api/account/signature_verification_key Update JWT signature verification key.

# Lookup tables

Type Resource Description
GET /api/managed_users/:managed_user_id/lookup_tables List tables.
GET /api/managed_users/:managed_user_id/lookup_tables/
:lookup_table_id/lookup		 Look up rows.
GET /api/managed_users/:managed_user_id/lookup_tables/
:lookup_table_id/rows		 List rows.
GET /api/managed_users/:managed_user_id/lookup_tables/
:lookup_table_id/rows/:row_id		 List rows in a lookup table.
POST /api/managed_users/:managed_user_id/lookup_tables/
:lookup_table_id/rows		 Add a row to a lookup table.
POST /api/managed_users/:managed_user_id/lookup_tables Create a new lookup table.
POST /api/managed_users/:managed_user_id/lookup_tables/batch_delete Delete lookup tables in batch.
PUT /api/managed_users/:managed_user_id/lookup_tables/
:lookup_table_id/rows/:row_id		 Update a row in a lookup table.
DELETE /api/managed_users/:managed_user_id/lookup_tables/
:lookup_table_id/rows/:row_id		 Delete a row in a lookup table.

# Manage customers

Type Resource Description
POST /api/managed_users Create customer.
PUT /api/managed_users/:id Update customer.
DELETE /api/managed_users/:id Delete customer.
GET /api/managed_users/:id Get customer.
GET /api/managed_users/ Get a list of all customers.
GET /api/managed_users/members Get a list of all members in a customer workspace.
GET /api/managed_users/members/:member_id Get a member in a customer workspace.
POST /api/managed_users/:id/members Add member to customer workspace.
PUT /api/managed_users/members/:member_id Update a member in a customer workspace.
DELETE /api/managed_users/:id/members/:member_id Remove member from customer workspace.
GET /api/managed_users/:id/connections List customer connections.
POST /api/v2/managed_users/statistics/usage Retrieve usage metrics for customer workspaces with enhanced data granularity.
POST /api/v2/managed_users/statistics/connection_usage Retrieve connection-based usage metrics for specified customer workspaces.
GET /api/managed_users/usage Get task usage of all customers by month.
POST /api/managed_users/managed_customer_id/environments Provision Environments for a customer.

# On-prem

Type Resource Description
GET /api/v2/managed_users/:id/on_prem_groups List on-prem groups in a customer workspace.
GET /api/v2/managed_users/:id/on_prem_agents List on-prem agents in a customer workspace.
GET /api/v2/managed_users/:id/on_prem_agents/:agent_id Retrieve the details of a specific on-prem agent in a customer workspace using its ID.

# Projects

Type Resource Description
GET /api/managed_users/:managed_user_id/projects List projects in a customer workspace.
POST /api/managed_users/:managed_user_id/folders Create a project in a customer workspace.
PUT /api/managed_users/:managed_user_id/projects/
:project_id		 Update a project in a customer workspace.
DELETE /api/managed_users/:managed_user_id/projects/
:project_id		 Delete a project in a customer workspace.
GET /api/managed_users/:managed_user_id/properties List project-level properties by prefix and project ID.
POST /api/managed_users/:managed_user_id/properties Upsert project-level properties.
GET /api/managed_users/:managed_user_id/deployments Retrieve a list of deployments in a customer workspace.
GET /api/managed_users/:managed_user_id/deployments/:id Retrieve a single deployment in a customer workspace.
GET /api/managed_users/:managed_user_id/api/project_builds/:id Retrieve a downloaded package in a customer workspace.
POST /api/managed_users/:managed_user_id/projects/:id/build Build a project in a customer workspace.
POST /api/managed_users/:managed_user_id/project_builds/:id/
deploy		 Deploy a downloaded package in a customer workspace.
POST /api/managed_users/:managed_user_id/projects/:project_id/
deploy		 Deploy a project in a customer workspace.
GET /api/managed_users/:managed_user_id/deployments/:id/
eligible_reviewers		 Retrieve a list of eligible reviewers that can be assigned to review a deployment in a customer workspace.
POST /api/managed_users/:managed_user_id/deployments/:id/
assign_reviewers		 Assign reviewers to a deployment in a customer workspace.
POST /api/managed_users/:managed_user_id/deployments/:id/
submit_for_review		 Submit a deployment for review in a customer workspace.
POST /api/managed_users/:managed_user_id/deployments/:id/
deploy		 Deploy an approved deployment in a customer workspace.

# Picklists

Type Resource Description
POST /api/managed_users/:id/connections/:connection_id/pick_list Obtains a list of picklist values for a specified connection in an Embedded customer workspace.

# Recipes

Type Resource Description
GET /api/managed_users/:id/recipes List recipes belonging to a customer.
GET /api/managed_users/:id/recipes/:recipe_id Get details of a recipe belonging to a customer.
POST /api/managed_users/:managed_user_id/recipes Create a recipe in a customer workspace.
PUT /api/managed_users/:managed_user_id/recipes/:id Update a recipe in a customer workspace.
POST /api/managed_users/:id/recipes/:recipe_id/copy Copy a recipe in a customer workspace.
DELETE /api/managed_users/:id/recipes/:recipe_id Delete a recipe in a customer workspace.
PUT /api/managed_users/:managed_user_id/recipes/:recipe_id/start Start a recipe in a customer workspace.
PUT /api/managed_users/:managed_user_id/recipes/:recipe_id/stop Stop a recipe in a customer workspace.
POST /api/managed_users/:managed_user_id/recipes/:recipe_id/
reset_trigger		 Reset the trigger for a recipe in a customer workspace.
POST /api/managed_users/:managed_user_id/recipes/:recipe_id/
poll_now		 Start a poll-now recipe.
GET /api/v2/managed_users/:managed_user_id/recipes/:recipe_id/
versions		 Get versions of a recipe belonging to a customer.
GET /api/v2/managed_users/:managed_user_id/recipes/:recipe_id/
versions/:id		 Get details of a recipe version belonging to a customer.
PATCH/PUT /api/v2/managed_users/:managed_user_id/recipes/:recipe_id/
versions/:id		 Update a recipe version comment in a customer workspace.

# Recipe lifecycle management

WHO CAN USE THESE ENDPOINTS?

The endpoints in this guide are Embedded Partner APIs. Contact your Workato representative for more info.

Looking for APIs to export packages? Refer to the Workato API docs.

Type Resource Description
GET /api/managed_users/:managed_user_id/
export_manifests/folder_assets		 View assets in a folder.
POST /api/managed_users/:managed_user_id/export_manifests Create an export manifest.
PUT /api/managed_users/:managed_user_id/export_manifests/:id Update an export manifest.
GET /api/managed_users/:managed_user_id/export_manifests/:id View an export manifest.
DELETE /api/managed_users/:managed_user_id/export_manifests/:id Delete an export manifest.
POST /api/managed_users/:managed_user_id/imports Import a package into a folder located in a customer workspace.
GET /api/managed_users/:managed_user_id/recipes Get status of an imported package.
POST /api/managed_users/:managed_user_id/exports/:manifest_id Export package based on the manifest ID. Requires the oem_vendor privilege.
GET /api/managed_users/:managed_user_id/exports/:package_id Returns the status of a package export. Requires the oem_vendor privilege.

# Roles

Type Resource Description
GET /api/managed_users/:id/roles List custom roles in a customer workspace.
POST /api/managed_users/:id/roles/:role_id/copy Makes a copy of a custom role.

# Tag assignments

Type Resource Description
POST /api/v2/managed_users/:id/tags_assignments Apply or remove asset tags in a customer workspace.

# Test Automation

Type Resource Description
POST /api/managed_users/:managed_user_id/
test_cases/run_requests		 Run test cases in a customer workspace.
GET /api/managed_users/:managed_user_id/recipes/
:recipe_id/test_cases		 List test cases for a specific recipe in a customer workspace.
GET /api/managed_users/:managed_user_id/test_cases/
run_requests/:test_id		 Get the current state of a test case run request in a customer workspace.
← Shared connector
API platform →


Last updated: 5/1/2025, 5:51:43 PM

On this page