Product UpdatesStatus PageAutomation Institute
English
Embedded API
Resources

# Workato API - Manage Customers

WHO CAN USE THESE ENDPOINTS?

The endpoints in this guide are Embedded Vendor APIs and require the oem_vendor privilege. Contact your Workato representative to enable this privilege in your account.

The Managed Users resource provides the ability to programmatically manage customers.

# Quick Reference

DEPRECATED ENDPOINTS

Deprecated endpoints will continue to work, but will not be updated after deprecation.

The Managed Users resource contains the following endpoints:

Type Resource Description
POST /api/managed_users Create a customer.
PUT /api/managed_users/:id Update a customer.
DELETE /api/managed_users/:id Delete a customer.
GET /api/managed_users/:id Get a customer.
GET /api/managed_users/ List all customers.
GET /api/managed_users/:id/members List members in a customer workspace.
GET /api/managed_users/:id/members/:member_id Get a member in a customer workspace.
POST /api/managed_users/:id/members Add a member to a customer workspace.
PUT /api/managed_users/:id/members/:member_id Update a member in a customer workspace.
DELETE /api/managed_users/:id/members/:member_id Remove a member from a customer workspace.
GET /api/managed_users/:id/connections List connections in a customer workspace.
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.
PUT /api/managed_users/:id/upgrade Deprecated. Upgrade customer.
PUT /api/managed_users/:id/downgrade Deprecated. Downgrade customer.
POST /api/managed_users/:id/member Deprecated. Add member to customer workspace.
DELETE /api/managed_users/:id/member Deprecated. Remove member from customer workspace.

# Create customer

Create a new Embedded customer.

POST /api/managed_users

# Payload

Name Type Description
name string
required		 Full name of the user.
notification_email string
required		 Email for error and administrative notifications.
plan_id string
optional		 Plan id. Default plan id is used when not provided.
external_id string
optional		 External identifier for the Embedded customer.
origin_url string
optional		 Applies to Embedded account customers. Provide a value if the embedded IFrame is hosted in a non-default origin page. For example, customer specific custom domains. Defaults to the origin configured at the account level.
frame_ancestors string
optional		 Provide one or more comma-separated frame ancestors. These URLs are used in the Content-Security-Policy HTTP header to allow rendering of Workato IFrames.
whitelisted_apps array
optional		 A list of connection provider values pertaining to the apps the customer is allowed to access. For more info about this feature, check out the Admin Console App access guide.
time_zone string
optional		 Timezone name. View this document for a list of timezones. Defaults to PST if not specified.
auth_settings object
optional		 Authentication settings to the customer. Accepted types are workato_auth and saml_sso. When configuring saml_sso, accepted providers are "okta", "onelogin", "others". See the sample requests below for examples.
full_embedding boolean
optional		 When set to true end users are sent to the customer's origin_url. Set to false to turn off the fully embedded redirect process at the customer workspace level. If you do not specify this value it defaults to null and inherits this value (true or false) from the Embedded partner's admin settings.

# Sample Requests

# Request with Workato authentication

curl  -X POST https://www.workato.com/api/managed_users \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d '{
            "name": "Kevin Leary",
            "notification_email": "kevinl@acme.com",
            "external_id": "UU0239093498",
            "whitelisted_apps": ["salesforce", "netsuite"],
            "time_zone": "Central Time (US & Canada)",
            "auth_settings": {
                "type": "workato_auth"
              },
            "full_embedding": false
          }'

# Request with SAML SSO and metadata URL

curl  -X POST https://www.workato.com/api/managed_users \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d '{
            "name": "Kevin Leary",
            "notification_email": "kevinl@acme.com",
            "external_id": "UU0239093498",
            "whitelisted_apps": ["salesforce", "netsuite"],
            "time_zone": "Central Time (US & Canada)",
            "auth_settings": {
              "type": "saml_sso",
              "provider": "okta",
              "metadata_url": "https://workato.okta.com/app/1234567890abcdefg123/sso/saml/metadata"
            },
            "full_embedding": false
          }'

# Request with SAML SSO and X509 cert

curl  -X POST https://www.workato.com/api/managed_users \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d '{
            "name": "Kevin Leary",
            "notification_email": "kevinl@acme.com",
            "external_id": "UU0239093498",
            "whitelisted_apps": ["salesforce", "netsuite"],
            "time_zone": "Central Time (US & Canada)",
            "auth_settings": {
              "type": "saml_sso",
              "provider": "okta",
              "sso_url": "https://dev-workato.okta.com/app/dev-w_workato_1/exk21ojjvq6212R6e5d7/sso/saml",
              "saml_issuer": "http://www.okta.com/exk21ojjvq6212R6e5d7",
              "x509_cert": "sfas"
              },
            "full_embedding": false
          }'

# Response

{
    "id": 14242,
    "external_id": "128490",
    "name": "B-max",
    "environments": [],
    "notification_email": "admin@bmax.com",
    "plan_id": "business_yearly",
    "origin_url": null,
    "frame_ancestors": null,    
    "trial": false,
    "in_trial": false,
    "whitelisted_apps": [
        "netsuite",
        "salesforce"
    ],
    "created_at": "2021-11-29T23:52:07.025-08:00",
    "updated_at": "2021-11-29T23:52:07.025-08:00",
    "time_zone": "Alaska",
    "auth_settings": {
        "type": "workato_auth"
    },
    "full_embedding": false
}

# Update customer

PUT /api/managed_users/:id

Updates the information for an existing Embedded customer's account, including:

  • Name
  • External ID
  • Error notification email address
  • Plan
  • Trial state
  • Authentication settings

Additional notes:

  • For customers in task-based plans, use this endpoint to update the task limit override and make a one-time adjustment.
  • For partners using Embedded, use this endpoint to update the custom origin URL of a specific customer

# URL Parameters

Name Type Description
id string
required		 Embedded customer ID/external ID.
External ID must be prefixed with an E (for example, EA2300) and the resulting ID should be URL encoded.

# Payload

Note: Properties are updated only if the payload contains the property. To clear the value of a property, set the property to null in the payload.

Name Type Description
name string
optional		 Full name of the user.
notification_email string
optional		 Email for error and administrative notifications.
error_notification_emails string
optional		 Emails for error notifications. This property overrides what you input in notification email property.
admin_notification_emails string
optional		 Emails for administrative notifications. This property overrides what you input in notification email property.
external_id string
optional		 External identifier for the Embedded customer.
origin_url string
optional		 Applies to Embedded account customers. Provide a value if the embedded IFrame is hosted in a non-default origin page(For example, customer specific custom domains etc). Defaults to the origin configured at the account level.
frame_ancestors string
optional		 Provide one or more comma-separated frame ancestors. These URLs are used in the Content-Security-Policy HTTP header to allow rendering of Workato IFrames.
plan_id string
optional		 The ID of the plan
in_trial boolean
optional		 Downgrade or upgrade the user to/from a free plan and subscription plan
task_limit_adjustment string
optional		 Task limit adjustment for current accounting period. Only valid for task-based plans. This adjustment will not apply to subsequent periods. Make a negative adjustment by adding "-" (eg. "-5000").
custom_task_limit string
optional		 Overrides the current plan limit.
whitelisted_apps array
optional		 A list of connection provider values pertaining to the apps the customer is allowed to access. For more info about this feature, check out the Admin Console App access guide.
time_zone string
optional		 Timezone name. View this document for a list of timezones. Defaults to PST if not specified.
auth_settings object
optional		 Authentication settings to the customer. Accepted types are workato_auth and saml_sso. When configuring saml_sso, accepted providers are "okta", "onelogin", "others". See the sample requests below for examples.
billing_start_date string
optional		 Set the current billing start date. The date should be provided in ISO 8601 format.
full_embedding boolean
optional		 When set to true end users are sent to the customer's origin_url. Set to false to turn off the fully embedded redirect process at the customer workspace level. If you do not specify this value it defaults to null and inherits this value (true or false) from the Embedded partner's admin settings.

# Sample Request

curl  -X PUT https://www.workato.com/api/managed_users/3498583 \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d '{
            "notification_email": "kevinl+workatodevops@acme.com",
            "admin_notification_emails": "kim@acme.com, jin@acem.com",
            "error_notification_emails": "kim@acme.com, john@acem.com",
            "whitelisted_apps": ["salesforce", "netsuite"],
            "auth_settings": {
              "type": "saml_sso",
              "provider": "okta",
              "metadata_url": "https://workato.okta.com/app/1234567890abcdefg123/sso/saml/metadata"
            },
            "billing_start_date": "2023-06-02",
            "full_embedding": false
          }'

# Response

{
    "id": 3498583,
    "external_id": "",
    "name": "Kevin K Leary",
    "environments": [],
    "notification_email": "kim@acme.com, jin@acem.com, john@acem.com",
    "error_notification_emails": "kim@acme.com, jin@acem.com",
    "admin_notification_emails": "kim@acme.com, john@acem.com",
    "plan_id": "task_plan_1",
    "origin_url": null,
    "frame_ancestors": null,
    "trial": false,
    "in_trial": false,
    "created_at": "2019-05-16T21:21:48.320-07:00",
    "updated_at": "2020-10-02T02:49:42.644-07:00",
    "current_billing_period_start": "2020-09-22T19:15:11.372-07:00",
    "current_billing_period_end": "2020-10-22T19:15:11.372-07:00",
    "task_limit_adjustment": null,
    "task_limit": 20000,
    "task_count": 0,
    "active_connection_limit": 0,
    "active_connection_count": 8,
    "active_recipe_count": 0,
    "whitelisted_apps": [
        "salesforce",
        "netsuite"
    ],
    "auth_settings": {
        "type": "saml_sso",
        "provider": "okta",
        "metadata_url": "https://workato.okta.com/app/1234567890abcdefg123/sso/saml/metadata"
    },
    "billing_start_date": "2020-09-22",
    "full_embedding": false,
    "time_zone": "Alaska"
}

# Delete customer

Proceed with caution!

Once deleted, customer workspaces aren't fully recoverable. Use caution when using this endpoint.

Deletes an Embedded customer.

DELETE /api/managed_users/:id

# URL parameters

Name Type Description
id string
required		 Embedded customer ID/external ID.
External ID must be prefixed with an E (for example, EA2300) and the resulting ID should be URL encoded.

# Sample Request

curl  -X DELETE https://www.workato.com/api/managed_users/28942 \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \

# Response

{
    "success": true
}

# Get customer

Retrieve details about an Embedded customer's account.

GET /api/managed_users/:id

# URL Parameters

Name Type Description
id string
required		 Embedded customer ID/external ID.
External ID must be prefixed with an E (for example, EA2300) and the resulting ID should be URL encoded.

# Sample Request

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

# Response

{
    "id": 4243,
    "external_id": "",
    "name": "Abstergo Industries",
    "environments": [
        {
            "id": 4244,
            "environment_type": "prod"
        },
        {
            "id": 4245,
            "environment_type": "test"
        }
    ],
    "notification_email": "kim@acme.com, jin@acem.com, john@acem.com",
    "error_notification_emails": "kim@acme.com, jin@acem.com",
    "admin_notification_emails": "kim@acme.com, john@acem.com",
    "plan_id": "tbp_wrike_monthly_1",
    "whitelisted_apps": ["salesforce", "netsuite"],
    "origin_url": null,
    "frame_ancestors": null,
    "trial": false,
    "in_trial": false,
    "created_at": "2019-05-16T21:21:48.320-07:00",
    "updated_at": "2020-09-23T04:01:26.844-07:00",
    "current_billing_period_start": "2020-09-22T19:15:11.372-07:00",
    "current_billing_period_end": "2020-10-22T19:15:11.372-07:00",
    "task_count": 0,
    "active_connection_limit": 0,
    "active_connection_count": 8,
    "active_recipe_count": 0,
    "auth_settings": {
        "type": "saml_sso",
        "provider": "okta",
        "metadata_url": "https://workato.okta.com/app/1234567890abcdefg123/sso/saml/metadata"
    },
    "full_embedding": false,
    "time_zone": "Alaska"
}

# Get list of customers

Get a list of all customers. This endpoint returns the data in the customer table of the Admin Console.

GET /api/managed_users/

# URL Parameters

Name Type Description
page integer Page number. Defaults to 1.
per_page integer Page size. Defaults to 100 (maximum is 100).

# Sample Request

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

# Response

TIP

The task count returned by this endpoint refers to the tasks done in the billing period of the customer.

{
    "result": [
        {
            "id": 4243,
            "external_id": "",
            "name": "Abstergo",
            "environments": [
                    {
                        "id": 4244,
                        "environment_type": "prod"
                    },
                    {
                        "id": 4245,
                        "environment_type": "test"
                    }
                ],
            "notification_email": "kim@abstergo.com, jin@abstergo.com, john@abstergo.com",
            "error_notification_emails": "kim@abstergo.com, jin@abstergo.com",
            "admin_notification_emails": "kim@abstergo.com, john@abstergo.com",
            "whitelisted_apps": ["salesforce", "netsuite"],
            "plan_id": "plan_tier1",
            "origin_url": null,
            "frame_ancestors": null,
            "trial": false,
            "in_trial": false,
            "created_at": "2019-05-16T21:21:48.320-07:00",
            "updated_at": "2020-10-01T02:59:32.845-07:00",
            "current_billing_period_start": "2020-09-18T05:34:50.215-07:00",
            "current_billing_period_end": "2020-10-18T05:34:50.215-07:00",
            "task_limit_adjustment": null,
            "task_limit": 20000,
            "task_count": 16777,
            "active_connection_limit": 0,
            "active_connection_count": 8,
            "active_recipe_count": 0,
            "time_zone": "Pacific Time (US & Canada)",
            "auth_settings": {
              "type": "workato_auth"
            },
            "full_embedding": false
        },
        {
            "id": 4772,
            "external_id": "101",
            "name": "Carly's Company",
            "environments": [],
            "notification_email": "carly.frederick@w.com, jack@w.com",
            "error_notification_emails": "carly.frederick@w.com",
            "admin_notification_emails": "jack@w.com",
            "whitelisted_apps": ["salesforce", "netsuite"],
            "plan_id": "business_yearly",
            "origin_url": null,
            "frame_ancestors": null,
            "trial": false,
            "in_trial": false,
            "created_at": "2019-07-30T12:39:59.895-07:00",
            "updated_at": "2020-07-20T15:30:07.168-07:00",
            "time_zone": "Pacific Time (US & Canada)",
            "current_billing_period_start": "2020-09-30T12:39:59.936-07:00",
            "current_billing_period_end": "2020-10-30T12:39:59.936-07:00",
            "task_count": 0,
            "active_connection_limit": 0,
            "active_connection_count": 0,
            "active_recipe_count": 0,
            "auth_settings": {
              "type": "workato_auth"
            },
            "full_embedding": false
        }
      ]
}

# Get list of customer workspace members

Gets a list of team members in a customer workspace. Returns the id, grant_type (either team member or customer manager), name, email, external_id, role_name, and time_zone of workspace members.

GET /api/managed_users/:id/members

# URL parameters

Name Type Description
id string
required		 Embedded customer ID/external ID.
External ID must be prefixed with an E (for example, EA2300) and the resulting ID should be URL encoded.

# Sample request

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

# Response

[
    {
        "id": 1680,
        "grant_type": "team",
        "role_name": "Admin",
        "external_id": null,
        "name": "James Bourne",
        "email": "jason_bourne@workato.com",
        "time_zone": "Pacific Time (US & Canada)"
    },
    {
        "id": 2641,
        "grant_type": "customer_manager",
        "role_name": "Admin",
        "external_id": null,
        "name": "Jason Bond",
        "email": "jason_bond@workato.com",
        "time_zone": "Eastern Time (US & Canada)"
    }
]

# Get customer workspace member

Get information for a specific team member in a customer workspace. Returns the id, grant_type (either team member or customer manager), name, email, external_id, role_name, and time_zone of the specified member.

GET /api/managed_users/:id/members/:member_id

# URL Parameters

Name Type Description
id string
required		 Embedded customer ID/external ID.
External ID must be prefixed with an E (for example, EA2300) and the resulting ID should be URL encoded.
member_id string
required		 The ID of the member.

# Sample request

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

# Response

{
    "id": 1680,
    "grant_type": "team",
    "role_name": "Admin",
    "external_id": null,
    "name": "James Bourne",
    "email": "jason_bourne@workato.com",
    "time_zone": "Pacific Time (US & Canada)"
}

# Add member to customer workspace

Add a member to the specified Embedded customer workspace.

POST /api/managed_users/:id/members

# URL Parameters

Name Type Description
id string
required		 Embedded customer ID/external ID.
External ID must be prefixed with an E (for example, EA2300) and the resulting ID should be URL encoded.

# Payload

Name Type Description
name string
required		 Full name of the user.
oauth_id string
optional		 Identifier used for OAuth.
role_name string
required		 Role name.
external_id string
optional		 External identifier for the member.
time_zone string
optional		 Timezone name. View this document for a list of timezones. Defaults to PST if not specified.

# Sample Request

curl  -X POST https://www.workato.com/api/managed_users/27819/members \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d '{
            "name": "Jack Smith",
            "role_name": "Admin",
            "external_id": "UU0239093499"
          }'

# Response

{
  "id": 3498583,
  "plan_id": "oem_plan",
  "trial": false,
  "time_zone": "Pacific Time (US & Canada)"
}

# Update customer workspace member

Updates a member in an existing Embedded customer workspace. Note: Only members added through the API can be updated using this endpoint.

PUT /api/managed_users/:id/members/:member_id

# URL Parameters

Name Type Description
id string
required		 Embedded customer ID/external ID.
External id should be prefixed with an E (for example, EA2300) and the resulting ID should be URL encoded.
member_id string
required		 The ID of the member.

# Payload

Name Type Description
oauth_id string
optional		 Identifier used for OAuth.
role_name string
optional		 Role name.
external_id string
optional		 External identifier for the member.
time_zone string
optional		 Timezone name. View this document for a list of timezones. Defaults to PST if not specified.

# Sample request

curl  -X PUT 'https://www.workato.com/api/managed_users/27819/members/12341' \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d '{
            "role_name": "Operator",
            "external_id": "UU0239093499"
          }'

# Response

{
  "id": 3498583,
  "plan_id": "oem_plan",
  "trial": false,
  "time_zone": "Pacific Time (US & Canada)"
}

# Remove member from customer workspace

Remove a member from an Embedded customer's account. Note: This endpoint only removes the member from the team - it doesn't delete their Workato account.

DELETE /api/managed_users/:id/members/:member_id

# URL Parameters

Name Type Description
id string
required		 Embedded customer ID/external ID.
External id should be prefixed with an E (for example, EA2300) and the resulting ID should be URL encoded.
member_id string
required		 The ID of the member.

# Sample Request

curl  -X DELETE 'https://www.workato.com/api/managed_users/27819/members/12314' \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \

# Response

{
  "id": 3485434779
}

# List customer connections

Get a list of connections in an Embedded customer's account.

GET /api/managed_users/:id/connections

# URL parameters

Name Type Description
id string
required		 Embedded customer ID/external ID.
External ID must be prefixed with an E (for example, EA2300) and the resulting ID should be URL encoded.

# Sample request

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

# Response

{
  "result": [
    {
      "id": 6132,
      "name": "My Box account",
      "provider": "box",
      "authorization_status": "success",
      "authorized_at": "2019-09-10T18:20:08.854-07:00",
      "created_at": "2019-09-10T18:19:57.437-07:00",
      "updated_at": "2019-09-10T18:20:08.859-07:00"
    },
    {
      "id": 6131,
      "name": "My Salesforce account",
      "provider": "salesforce",
      "authorization_status": "success",
      "authorized_at": "2019-09-10T18:19:43.018-07:00",
      "created_at": "2019-09-10T18:19:12.902-07:00",
      "updated_at": "2019-09-10T18:19:43.021-07:00"
    }
  ]
}

# Get monthly usage

Get a list of monthly usage for all Embedded customers for the last 12 months. Task data is currently the only data available.

GET /api/managed_users/usage

TIP

The task count by customer returned by this endpoint is the total of all tasks done in the associated calendar month. You can obtain the total usage across all plans using this endpoint, even if the customer's plan has changed or the billing date/usage has been reset.

# Sample request

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

# Response

Note: The following response has been truncated from 12 to three months.

{
   "result":{
      "data":[
         {
            "user_id": 7443,
            "intervals":[
               {
                  "start_datetime": "2019-10-01T00:00:00.000-07:00",
                  "task_count": null
               },
               {
                  "start_datetime": "2019-11-01T00:00:00.000-07:00",
                  "task_count": null
               },
               {
                  "start_datetime": "2020-10-01T00:00:00.000-07:00",
                  "task_count": 0
               }
            ]
         }
      ],
      "generated_at":"2020-10-02T05:41:29.232-07:00"
   }
}

# Provision environments

Provision Environments for a customer you specify.

# Sample request

POST /api/managed_users/managed_customer_id/environments

# Sample response

{
    "data": {
        "status": "created",
        "id": 29069,
        "external_id": null,
        "name": "Barnaby",
        "environments": [
            {
                "id": 29541,
                "environment_type": "prod"
            },
            {
                "id": 29540,
                "environment_type": "test"
            }
        ],
        "notification_email": "example-email@example.com",
        "full_embedding": true,
        "admin_notification_emails": "example-email@example.com ",
        "error_notification_emails": "example-email@example.com",
        "plan_id": "premium_quarterly",
        "origin_url": null,
        "trial": false,
        "in_trial": false,
        "whitelisted_apps": [],
        "frame_ancestors": null,
        "created_at": "2023-11-13T23:59:29.420-09:00",
        "updated_at": "2024-02-29T06:02:58.078-09:00",
        "time_zone": "Pacific Time (US & Canada)",
        "auth_settings": {
            "type": "workato_auth"
        },
        "current_billing_period_start": "2024-03-08T08:19:19.079-09:00",
        "current_billing_period_end": "2024-04-08T09:19:19.079-08:00",
        "task_count": 0,
        "active_connection_limit": 0,
        "active_connection_count": 5,
        "active_recipe_count": 5
    }
}
← Delete row
Picklists →


Last updated: 4/25/2024, 5:58:27 PM

On this page