# 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 structure allows you to precisely target each environment (Development, Test, and Production) when using the Environments feature for your customers.
# Standard access without Environments
The standard Embedded API allows you to interact with customers regardless of whether they have Environments provisioned. You must add the user_id directly to the endpoint: /api/managed_users/: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/:user_id_dev - Test: Access the test environment using
/api/managed_users/:user_id_test - Production: Access the production environment using
/api/managed_users/:user_id_prod
For guidance on targeting the correct environment, refer to the Embedded Environments APIs (opens new window) section in the Workato documentation.
# Authentication
To authenticate to the API, create an API Client in Workspace admin. 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
- Data retention
- Environment properties
- Folders
- Jobs
- JWT direct link configurations
- Lookup tables
- Manage customers
- Picklists
- Project properties
- Recipes
- Recipe lifecycle management
- Roles
- 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 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 disconnected 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. |
# Data retention
| Type | Resource | Description |
|---|---|---|
| PUT | /api/managed_users/:managed_user_id/update_data_retention | Update a customer workspace's data retention period. |
# 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. |
# Folders
| Type | Resource | Description |
|---|---|---|
| GET | /api/managed_users/:id/folders | List folders in a customer workspace. |
| POST | /api/managed_users/:id/folders | Creates a new folder in a customer workspace. |
| DELETE | /api/managed_users/:managed_user_id/folders/:folder_id | Delete a folder. |
# 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. |
| 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. |
# Projects and project properties
| Type | Resource | Description |
|---|---|---|
| POST | /api/managed_users/managed_customer_id/projects/:project_id/deploy?environment_type={env} | Deploy a project. |
| GET | /api/managed_users/:managed_user_id/projects | List projects. |
| DELETE | /api/managed_users/:managed_user_id/projects/:project_id | Delete a project. |
| GET | /api/managed_users/:managed_user_id/properties | List project-level properties that match a prefix and project ID. |
| POST | /api/managed_users/:managed_user_id/properties | Upsert project-level properties. |
# 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. |
| GET | /api/recipes/search | Search for public recipes. |
| 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. |
# 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. |
# 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 | Runs test cases in a customer workspace. |
Last updated: 4/25/2024, 5:58:27 PM