# 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 account
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 account is allowed to access. For more info about this feature, check out the OEM 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 account. 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 account's origin_url. Set to false to turn off the fully embedded redirect process at the customer account 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 Account
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 Account ID/External ID. External ID must be prefixed with an E(eg: 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 account is allowed to access. For more info about this feature, check out the OEM 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 account. 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 account's origin_url. Set to false to turn off the fully embedded redirect process at the customer account 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 Account
Proceed with caution!
Once deleted, customer accounts aren't fully recoverable. Use caution when using this endpoint.
Deletes an Embedded customer account.
DELETE /api/managed_users/:id
# URL parameters
| Name | Type | Description |
|---|---|---|
| id | string required | Embedded customer Account ID/External ID. External ID must be prefixed with an E(eg: 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 Account
Retrieve details about an Embedded customer's account.
GET /api/managed_users/:id
# URL Parameters
| Name | Type | Description |
|---|---|---|
| id | string required | Embedded customer Account ID/External ID. External ID must be prefixed with an E(eg: 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 Customer Accounts
Get a list of all customer accounts. 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 Account Members
Gets a list of team members in a customer account. Returns the id, grant_type (either team member or customer manager), name, email, external_id, role_name, time_zone of account members.
GET /api/managed_users/:id/members
# URL parameters
| Name | Type | Description |
|---|---|---|
| id | string required | Embedded customer Account ID/External ID. External ID must be prefixed with an E(eg: 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 Account Member
Get information for a specific team member in a customer account. Returns the id, grant_type (either team member or customer manager), name, email, external_id, role_name, time_zone of the specified member.
GET /api/managed_users/:id/members/:member_id
# URL Parameters
| Name | Type | Description |
|---|---|---|
| id | string required | Embedded customer Account ID/External ID. External ID must be prefixed with an E(eg: 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 Account
Add a member to the specified Embedded customer account.
POST /api/managed_users/:id/members
# URL Parameters
| Name | Type | Description |
|---|---|---|
| id | string required | Embedded customer Account ID/External ID. External ID must be prefixed with an E(eg: 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 Account Member
Updates a member in an existing Embedded customer account. Note: Only members added via 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 Account ID/External ID. External id should be prefixed with a E(eg: 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 account
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 Account ID/External ID. External id should be prefixed with a E(eg: 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 account ID/External ID. External ID must be prefixed with an E(eg: 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
}
}
Last updated: 3/20/2024, 3:44:54 PM