# 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

Name	Description	Sample reply
`200`	Success	`{"Success": true}`
`400`	Bad request	`{"message": "Bad request"}`
`401`	Unauthorized	`{"message": "Unauthorized"}`
`404`	Not found	`{"message": "Not found"}`
`500`	Server error	`{"message":"Server error","id":"3188c2d0-29a4-4080-908e-582e7ed82580"}`

# Resources

API platform
Connections
Connectors
Custom connectors
Custom OAuth profiles
Customer managers
Customer workspace collaborators
Data retention
Dynamic field mapping
Environment management
Environment properties
Environments
Folders
Jobs
JWT direct link configurations
Lookup tables
Manage customers
On-prem
Picklists
Projects
Recipes
Recipe lifecycle management
Roles
Tag assignments
Team collaborators
Test Automation

# 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.
POST	/api/managed_users/:id/ api_clients	Create 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.
POST	/api/managed_users/:id/ api_access_profiles	Create an access profile belonging to 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.
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.
PUT	/api/managed_users/:id/ api_access_profiles	Disable an access profile belonging to 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.

# 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.

# JWT direct link configurations

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/managed_users/:managed_user_id/recipes/:recipe_id/ versions	Get versions of a recipe belonging to a customer.
GET	/api/managed_users/:managed_user_id/recipes/:recipe_id/ versions/:id	Get details of a recipe version belonging to a customer.
PATCH/PUT	/api/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.

# Team collaborators

Type	Resource	Description
POST	/api/managed_users/:id/member_invitation	Invites a collaborator to your team.

# 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.

Last updated: 10/28/2024, 3:18:12 PM