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/

IL Data Center

https://app.il.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
• 400 Bad Request
• 401 Unauthorized
• 403 Forbidden
• 404 Not Found
• 500 Server Error

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"
        }
    ]
}