Embedded Environments APIs

Embedded APIs are fully compatible with Embedded Environments. You can continue to use the same Embedded API across all environments by targeting the appropriate user ID. When provisioning Environments for an existing Embedded Customer, their user ID becomes the Development user ID, and two new IDs are generated for the TEST and PROD Environments.

Embedded APIs with and without Environments

The base URL for all Embedded API interactions is:

.../api/managed_users/

Append the user_id to this base URL to interact with a specific customer. This enables you to manage each environment for customers with Environments provisioned by pointing to each workspace ID. If the customer doesn't have Environments provisioned, you can use the URL/api/managed_users/:user_id to interact with a specific customer.

Use the following API endpoints to target a specific environment within a customer's account:

• Development environment:/api/managed_users/:user_id_dev

• Test environment: /api/managed_users/:user_id_test

• Production environment: /api/managed_users/:user_id_prod

When you provision Environments for an existing customer, their original :user_id is designated for the Development environment (:user_id_dev), and new unique identifiers are generated for the Test and Production environments (:user_id_test and :user_id_prod, respectively). This ensures that each environment is accessible and manageable independently through the API. This provides precise control over the deployment and operation of integrations across different stages of development.

How to get the correct user ID

You can retrieve the IDs for your customers' environments using the Get List Of Customers API.

When listing your customers, those with Environments provisioned return the new property environments with the PROD and TEST environments IDs.

Sample request

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

Response

{
        {
            "id": 29727, //this is the used_id for a customer without ENVs
            "external_id": null,
            "name": "new",
            "environments": [],
            "notification_email": "virginia2@workato.com",
            ...
        },
        {
            "id": 29833, //this is the used_id_dev for a customer with ENVs
            "external_id": null,
            "name": "Alex",
            "environments": [
                {
                    "id": 29835, //this is the used_id_prod for a customer with ENVs
                    "environment_type": "prod"
                },
                {
                    "id": 29834, //this is the used_id_test for a customer with ENVs
                    "environment_type": "test"
                }
            ],
            "notification_email": "alex@workato.com",
           ...
        }
}

External IDs for environments

You can also specify unique external IDs for each of your customers' Environments. External IDs enable you to manage customers programmatically in the same way as you do for customers without Environments.

To add an external ID, you can either Update the customer through the API or add it through the UI:

1

Navigate to Manage customers.

2

Click Settings > External IDs.

Exclusive development environment access

Certain API endpoints, designed for development activities like collaborator management, are exclusively accessible within the Development environment. An error displays if you try to access these endpoints from your TEST or PROD environments.

For example:

Sample request

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

Response

{
    "message": "Not Available for Environment"
}