# 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 customer accounts and assets, including recipes and connections.
# Base URL
The Embedded Partner APIs are a collection of endpoints for interacting with customer accounts, 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 URL
s 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 customer accounts
- 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 account. |
POST | /api/managed_users/:id/ api_collections | Create API collection in a customer account. |
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 account. |
POST | /api/managed_users/:id/ api_clients | Create API client in a customer account. |
GET | /api/managed_users/:id/ api_access_profiles | List access profiles belonging to an API client in a customer account. |
POST | /api/managed_users/:id/ api_access_profiles | Create an access profile belonging to an API client in a customer account. |
PUT | /api/managed_users/:id/ api_access_profiles | Update an access profile belonging to an API client in a customer account. |
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 account. |
PUT | /api/managed_users/:id/ api_access_profiles | Disable an access profile belonging to an API client in a customer account. |
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 account. |
POST | /api/managed_users/:managed_user_id/ connections | Allows the Embedded vendor to add a shell connection in a customer account. |
PUT | /api/managed_users/:managed_user_id/ connections/:connection_id | Updates a connection in a customer account. |
POST | /api/managed_users/:managed_user_id/ connections/:connection_id/disconnect | Disconnects a connection in a customer account. |
DELETE | /api/managed_users/:managed_user_id/ connections/:connection_id | Deletes a disconnected connection in a customer account. |
# 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 account that matches a prefix. |
POST | /api/managed_users/:managed_user_id/properties | Upserts environment properties to a customer account. |
# Folders
Type | Resource | Description |
---|---|---|
GET | /api/managed_users/:id/folders | List folders in a customer account. |
POST | /api/managed_users/:id/folders | Creates a new folder in a customer account. |
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 | Update customer. |
DELETE | /api/managed_users | 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 account. |
# Recipes
Type | Resource | Description |
---|---|---|
GET | /api/managed_users/:id/recipes | List recipes belonging to a customer account. |
GET | /api/managed_users/:id/recipes/:recipe_id | Get details of a recipe belonging to a customer account. |
GET | /api/recipes/search | Search for public recipes. |
POST | /api/managed_users/:managed_user_id/recipes | Create a recipe in a customer account. |
PUT | /api/managed_users/:managed_user_id/recipes/:id | Update a recipe in a customer account. |
POST | /api/managed_users/:id/recipes/:recipe_id/copy | Copy a recipe in a customer account. |
DELETE | /api/managed_users/:id/recipes/:recipe_id | Delete a recipe in a customer account. |
PUT | /api/managed_users/:managed_user_id/recipes/:recipe_id/start | Start a recipe in a customer account. |
PUT | /api/managed_users/:managed_user_id/recipes/:recipe_id/stop | Stop a recipe in a customer account. |
# 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 account. |
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 account. |
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/9/2024, 6:34:39 PM