# Manage customers
ENDPOINT AVAILABILITY
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. |
| POST | /api/v2/managed_users/statistics/usage | Retrieve usage metrics for customer workspaces with enhanced data granularity. |
| GET | /api/managed_users/usage | Get task usage of all customers by month. |
| POST | /api/managed_users/:id/environments | Provision Environments for an existing customer. |
| GET | /api/managed_users/:id/members/:member_id/privileges | List privileges for a particular member of a customer workspace that you specify. |
| 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. Refer to the Admin Console App access guide for more information. |
| 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 for the customer. Accepted types are workato_auth and saml_sso. When configuring saml_sso, accepted providers are "okta", "onelogin", "others". See the sample requests section 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. |
| provision_environments | boolean optional | When set to true, the new Embedded customer is provisioned with the Environments feature. Set to false by default. |
# 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": "[email protected]",
"provision_environments": false,
"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",
"provision_environments": false,
"notification_email": "[email protected]",
"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",
"provision_environments": false,
"notification_email": "[email protected]",
"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
}'
# Request with Environments enabled
curl -X POST https://www.workato.com/api/managed_users \
-H 'Authorization: Bearer <api_token>' \
-H 'Content-Type: application/json' \
-d '{
"name": "Test user",
"notification_email": "[email protected]",
"provision_environments": true
}'
# Response
{
"id": 32122,
"external_id": null,
"name": "Test user",
"environments": [
{
"id": 32124,
"environment_type": "prod",
"external_id": null
},
{
"id": 32123,
"environment_type": "test",
"external_id": null
},
{
"id": 32122,
"environment_type": "dev",
"external_id": null
}
],
"notification_email": "[email protected]",
"full_embedding": null,
"plan_id": "oem_enterprise",
"origin_url": null,
"whitelisted_apps": [],
"frame_ancestors": null,
"created_at": "2024-10-02T15:26:18.312-07:00",
"updated_at": "2024-10-02T15:26:18.312-07:00",
"time_zone": "Pacific Time (US & Canada)",
"auth_settings": {
"type": "workato_auth"
}
# Response
{
"id": 14242,
"external_id": "128490",
"name": "B-max",
"environments": [],
"notification_email": "[email protected]",
"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 an existing Embedded customer's account information. You can use this endpoint to update specific parameters, such as external_id and error_notification_emails, in both test and production environments. Include the environments key in the request payload to specify the environment.
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 '{
"name": "<string>",
"notification_email": "<string>",
"admin_notification_emails": "<string>",
"error_notification_emails": "<string>",
"in_trial": "<boolean>",
"task_limit_adjustment": "<number>",
"custom_task_limit": "<number>",
"billing_start_date": "<string>",
"environments": [
{
"environment_type": "test",
"external_id": "ext-ec-test-22",
"error_notification_emails": "<mailto:[email protected]|[email protected]>"
},
{
"environment_type": "prod",
"external_id": "ext-ec-prod-15",
"error_notification_emails": "<mailto:[email protected]|[email protected]>"
}
],
"external_id": "ext-ect-dev-13",
"error_notification_emails": "<mailto:[email protected]|[email protected]>",
"origin_url": "<string>",
"frame_ancestors": "<string>",
"plan_id": "<string>",
"time_zone": "Amsterdam",
"whitelisted_apps": [
"<string>",
"<string>"
],
"full_embedding": "<boolean>"
}'
# Response
{
"id": 8,
"external_id": "ext-ect-dev-13",
"name": "OEM customer 1",
"environments": [
{
"id": 13,
"environment_type": "test",
"external_id": "ext-ec-test-22"
},
{
"id": 14,
"environment_type": "prod",
"external_id": "ext-ec-prod-15"
},
{
"id": 8,
"environment_type": "dev",
"external_id": "ext-ect-dev-13"
}
],
"notification_email": "[email protected],[email protected]",
"full_embedding": null,
"admin_notification_emails": "[email protected]",
"error_notification_emails": "[email protected]",
"plan_id": "wrike_integrate",
"origin_url": null,
"trial": false,
"in_trial": false,
"whitelisted_apps": [],
"frame_ancestors": null,
"created_at": "2024-09-16T21:24:09.832-07:00",
"updated_at": "2024-10-09T01:02:38.686-07:00",
"time_zone": "Pacific Time (US & Canada)",
"auth_settings": {
"type": "workato_auth"
},
"current_billing_period_start": "2024-09-16T21:24:09.845-07:00",
"current_billing_period_end": "2024-10-16T21:24:09.845-07:00",
"task_count": 0,
"active_connection_limit": 0,
"active_connection_count": 0,
"active_recipe_count": 0,
"billing_start_date": "2024-09-16"
}
# Delete customer
ACCOUNT RECOVERABILITY
After you delete a customer account, it can't be fully recovered. 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>'
# Responses
# Without environments
{
"id": 27819,
"external_id": null,
"name": "ACME Automations",
"environments": [],
"notification_email": "[email protected]",
"full_embedding": null,
"admin_notification_emails": "[email protected]",
"error_notification_emails": "[email protected]",
"plan_id": "oem_enterprise",
"origin_url": null,
"trial": false,
"in_trial": false,
"whitelisted_apps": [],
"frame_ancestors": null,
"created_at": "2024-10-02T16:16:14.512-07:00",
"updated_at": "2024-10-02T16:16:14.512-07:00",
"time_zone": "Pacific Time (US & Canada)",
"auth_settings": {
"type": "workato_auth"
},
"current_billing_period_start": "2024-10-02T16:16:14.689-07:00",
"current_billing_period_end": "2024-11-02T16:16:14.689-07:00",
"task_count": 0,
"active_connection_limit": 0,
"active_connection_count": 0,
"active_recipe_count": 0
}
# With environments
{
"id": 27819,
"external_id": null,
"name": "ACME Automations",
"environments": [
{
"id": 27821,
"environment_type": "prod",
"external_id": null
},
{
"id": 27820,
"environment_type": "test",
"external_id": null
},
{
"id": 27819,
"environment_type": "dev",
"external_id": null
}
],
"notification_email": "[email protected]",
"full_embedding": null,
"admin_notification_emails": "[email protected]",
"error_notification_emails": "[email protected]",
"plan_id": "oem_enterprise",
"origin_url": null,
"trial": false,
"in_trial": false,
"whitelisted_apps": [],
"frame_ancestors": null,
"created_at": "2024-10-02T16:16:14.512-07:00",
"updated_at": "2024-10-02T16:16:14.512-07:00",
"time_zone": "Pacific Time (US & Canada)",
"auth_settings": {
"type": "workato_auth"
},
"current_billing_period_start": "2024-10-02T16:16:14.689-07:00",
"current_billing_period_end": "2024-11-02T16:16:14.689-07:00",
"task_count": 0,
"active_connection_limit": 0,
"active_connection_count": 0,
"active_recipe_count": 0
}
# 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 optional | Page number. Defaults to 1. |
| per_page | integer optional | 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>'
# Responses
TASK COUNT FOR BILLING PERIOD
The task count provided by this endpoint represents the number of tasks completed during the customer's billing period.
# Without environments
{
"result": [
{
"id": 27819,
"external_id": null,
"name": "ACME Automations",
"environments": [],
"notification_email": "[email protected]",
"full_embedding": null,
"admin_notification_emails": "[email protected]",
"error_notification_emails": "[email protected]",
"plan_id": "oem_enterprise",
"origin_url": null,
"trial": false,
"in_trial": false,
"whitelisted_apps": [],
"frame_ancestors": null,
"created_at": "2024-10-02T16:16:14.512-07:00",
"updated_at": "2024-10-02T16:16:14.512-07:00",
"time_zone": "Pacific Time (US & Canada)",
"auth_settings": {
"type": "workato_auth"
},
"current_billing_period_start": "2024-10-02T16:16:14.689-07:00",
"current_billing_period_end": "2024-11-02T16:16:14.689-07:00",
"task_count": 0,
"active_connection_limit": 0,
"active_connection_count": 0,
"active_recipe_count": 0
},
...
]
}
# With environments
{
"result": [
{
"id": 27819,
"external_id": null,
"name": "ACME Automations",
"environments": [
{
"id": 27821,
"environment_type": "prod",
"external_id": null
},
{
"id": 27820,
"environment_type": "test",
"external_id": null
},
{
"id": 27819,
"environment_type": "dev",
"external_id": null
}
],
"notification_email": "[email protected]",
"full_embedding": null,
"admin_notification_emails": "[email protected]",
"error_notification_emails": "[email protected]",
"plan_id": "oem_enterprise",
"origin_url": null,
"trial": false,
"in_trial": false,
"whitelisted_apps": [],
"frame_ancestors": null,
"created_at": "2024-10-02T16:16:14.512-07:00",
"updated_at": "2024-10-02T16:16:14.512-07:00",
"time_zone": "Pacific Time (US & Canada)",
"auth_settings": {
"type": "workato_auth"
},
"current_billing_period_start": "2024-10-02T16:16:14.689-07:00",
"current_billing_period_end": "2024-11-02T16:16:14.689-07:00",
"task_count": 0,
"active_connection_limit": 0,
"active_connection_count": 0,
"active_recipe_count": 0
}
...
]
}
# 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": "[email protected]",
"time_zone": "Pacific Time (US & Canada)"
},
{
"id": 2641,
"grant_type": "customer_manager",
"role_name": "Admin",
"external_id": null,
"name": "Jason Bond",
"email": "[email protected]",
"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": "[email protected]",
"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. The External ID must be URL encoded and prefixed with an E (for example, EA2300). |
# Payload
| Name | Type | Description |
|---|---|---|
| name | string required | The full name of the member. |
| role_name | string conditional | The role to assign the member. Required if env_roles is not provided. |
| env_roles | object conditional | The environment roles object. Required if role_name is not provided. |
| env_roles[environment_type] | string conditional | The type of environment in the customer workspace where you plan to add the member. Required if role_name is not provided. |
| env_roles[name] | string conditional | The role to assign the member for the specific environment. Required if role_name is not provided. |
| oauth_id | string optional | The identifier used for OAuth. |
| external_id | string optional | The external identifier for the member. |
| time_zone | string optional | The timezone name. Refer to the Timezone list section for more information. Defaults to PST if not specified. |
SPECIFY ROLES FOR DIFFERENT ENVIRONMENTS
You must provide either role_name or env_roles in the payload. role_name only assigns a role in the dev environment. Use env_roles to specify the environment type and role for other environments.
Workato does not support a mixed approach to assigning roles. This means that when you combine the env_roles and role_name in the payload, Workato ignores the role_name and only assigns the roles specified by the env_roles object.
# Sample requests
# Without environments
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: Without environments
{
"id": 12341,
"grant_type": "team",
"role_name": "Admin",
"external_id": "UU0239093499",
"name": "Jack Smith",
"email": "[email protected]",
"time_zone": "Pacific Time (US & Canada)",
"created_at": "2024-09-13T07:26:48.779-07:00",
"last_activity_log": null
}
# With environments
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",
"env_roles": [
{
"environment_type": "dev",
"name": "Admin"
},
{
"environment_type": "test",
"name": "Analyst"
},
{
"environment_type": "prod",
"name": "Operator"
}
],
"external_id": "UU0239093499"
}'
Response: With environments
{
"id": 12341,
"grant_type": "team",
"role_name": "Admin",
"external_id": "UU0239093499",
"name": "Jack Smith",
"email": "[email protected]",
"time_zone": "Pacific Time (US & Canada)",
"created_at": "2024-09-24T08:06:09.883-07:00",
"last_activity_log": null,
"env_roles": [
{
"environment_type": "dev",
"name": "Admin"
},
{
"environment_type": "test",
"name": "Analyst"
},
{
"environment_type": "prod",
"name": "Operator"
}
]
}
# Update customer workspace member
Updates a member in an existing Embedded customer workspace.
UPDATE MEMBER RESTRICTION
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. The External ID must be URL encoded and prefixed with an E (for example, EA2300). |
| member_id | string required | The ID of the member. |
# Payload
| Name | Type | Description |
|---|---|---|
| role_name | string optional | The updated role to assign the member. |
| env_roles | object optional | The environment roles object. |
| env_roles[environment_type] | string optional | The type of environment in the customer workspace where you plan to update the member's roles. |
| env_roles[name] | string optional | The updated role to assign the member for the specific environment. |
| oauth_id | string optional | The updated identifier used for OAuth. |
| external_id | string optional | The updated external identifier for the member. |
| time_zone | string optional | The updated timezone name. Refer to the Timezone list section for more information. Defaults to PST if not specified. |
# Sample requests
# Without environments
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"
}'
Response: Without environments
{
"id": 12341,
"grant_type": "team",
"role_name": "Operator",
"external_id": "UU0239093499",
"name": "Jack Smith",
"email": "[email protected]",
"time_zone": "Pacific Time (US & Canada)",
"created_at": "2024-10-07T13:52:11.346-07:00",
"last_activity_log": null
}
# With environments
curl -X PUT 'https://www.workato.com/api/managed_users/27819/members/12341' \
-H 'Authorization: Bearer <api_token>' \
-H 'Content-Type: application/json' \
-d '{
"env_roles": [
{
"environment_type": "dev",
"name": "Operator"
},
{
"environment_type": "test",
"name": "Operator"
},
{
"environment_type": "prod",
"name": "Operator"
}
]
}'
Response: With environments
{
"id": 12341,
"grant_type": "team",
"role_name": "Operator",
"external_id": "UU0239093499",
"name": "Jack Smith",
"email": "[email protected]",
"time_zone": "Pacific Time (US & Canada)",
"created_at": "2024-09-24T08:06:09.883-07:00",
"last_activity_log": null,
"env_roles": [
{
"environment_type": "dev",
"name": "Operator"
},
{
"environment_type": "test",
"name": "Operator"
},
{
"environment_type": "prod",
"name": "Operator"
}
]
}
# 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 usage (v2)
Retrieves usage metrics for specified customer workspaces within a defined time frame, including task usage, recipe counts, and counts of successful and failed jobs. This endpoint parses and returns datetime values in the Embedded admin's workspace timezone.
POST /api/v2/managed_users/statistics/usage
QUERY USAGE FOR MULTIPLE WORKSPACES IN A SINGLE REQUEST
We recommend querying usage for all relevant workspaces in a single request to optimize performance.
# Payload
| Name | Type | Description |
|---|---|---|
| from | string required | Start of the time range for retrieving usage metrics, in ISO 8601 format (YYYY-MM-DDTHH:mm:ss.SSSZ). |
| to | string required | End of the time range for retrieving usage metrics, in ISO 8601 format (YYYY-MM-DDTHH:mm:ss.SSSZ). |
| interval | string optional | Sets the time interval for aggregating results. Accepted values include none, year, month, week, day, and hour. Default is none. |
| workspace_ids[] | array of integers conditional | Customer workspace IDs to retrieve usage data for. Required if external_ids[] is not provided. |
| external_ids[] | array of strings conditional | Customer external IDs to retrieve usage data for. Required if workspace_ids[] is not provided. |
| folder_ids[] | array of integers optional | Filters results to the specified folder IDs, returning tasks and job outcomes within those folders. |
| recipe_ids[] | array of integers optional | Filters results to the specified recipe IDs, returning tasks and job outcomes related to those recipes. |
# Sample request
The following example request retrieves monthly usage statistics for specified customer workspaces (IDs 8, 16, and 17) between July 1, 2024, and September 26, 2024:
curl -X POST 'https://www.workato.com/api/v2/managed_users/statistics/usage' \
-H 'Authorization: Bearer <api_token>' \
-H 'Content-Type: application/json' \
-d '{
"interval": "month",
"workspace_ids": [8, 16, 17],
"from": "2024-07-01",
"to": "2024-09-26"
}'
# Response
{
"data": [
{
"workspace_id": 8,
"intervals": [
{
"start_datetime": "2024-07-01T00:00:00.000-07:00",
"successful_job_count": 1050,
"failed_job_count": 50,
"recipes_count": 3,
"task_count": 11000
},
{
"start_datetime": "2024-08-01T00:00:00.000-07:00",
"successful_job_count": 1300,
"failed_job_count": 60,
"recipes_count": 3,
"task_count": 13600
},
{
"start_datetime": "2024-09-01T00:00:00.000-07:00",
"successful_job_count": 1400,
"failed_job_count": 70,
"recipes_count": 3,
"task_count": 14800
}
]
},
{
"workspace_id": 16,
"intervals": [
{
"start_datetime": "2024-07-01T00:00:00.000-07:00",
"successful_job_count": 1150,
"failed_job_count": 55,
"recipes_count": 5,
"task_count": 12300
},
{
"start_datetime": "2024-08-01T00:00:00.000-07:00",
"successful_job_count": 1400,
"failed_job_count": 65,
"recipes_count": 6,
"task_count": 14500
},
{
"start_datetime": "2024-09-01T00:00:00.000-07:00",
"successful_job_count": 1550,
"failed_job_count": 75,
"recipes_count": 6,
"task_count": 16200
}
]
},
{
"workspace_id": 17,
"intervals": [
{
"start_datetime": "2024-07-01T00:00:00.000-07:00",
"successful_job_count": 1800,
"failed_job_count": 90,
"recipes_count": 2,
"task_count": 18500
},
{
"start_datetime": "2024-08-01T00:00:00.000-07:00",
"successful_job_count": 2100,
"failed_job_count": 100,
"recipes_count": 2,
"task_count": 23000
},
{
"start_datetime": "2024-09-01T00:00:00.000-07:00",
"successful_job_count": 2400,
"failed_job_count": 120,
"recipes_count": 2,
"task_count": 26000
}
]
}
],
"generated_at": "2024-09-26T13:48:46.839-07:00"
}
# Get monthly usage
Retrieves monthly usage metrics for all Embedded customers for the last 12 months. This endpoint returns datetime values in the Embedded admin's workspace timezone. Currently, only task data is available through this endpoint.
GET /api/managed_users/usage
GET USAGE V2 API
Use the Get usage (v2) endpoint to retrieve more granular task information for a specific date range, workspace, project, or recipe.
TASK COUNT BY CALENDAR MONTH
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 an existing customer that you specify.
# Sample request
POST /api/managed_users/: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": "[email protected]",
"full_embedding": true,
"admin_notification_emails": "[email protected] ",
"error_notification_emails": "[email protected]",
"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
}
}
# Get list of customer privileges
List privileges for a particular member of a customer workspace that you specify.
# Sample request
GET /api/managed_users/:id/members/:member_id/privileges
# Sample response
List privileges sample response
{
"data": [
{
"environment_type": "dev",
"name": "Customer Admin",
"privileges": {
"Collaborator SAML SSO auth": [
"all"
],
"Custom OAuth profiles": [
"read"
],
"Connection Folders": [
"all"
],
"Projects": [
"read"
],
"Folders": [
"read",
"update"
],
"Connections": [
"read",
"update"
],
"Recipes": [
"read",
"create",
"update",
"delete",
"run",
"read_run_history"
]
},
"folder_ids": [
40630
]
},
{
"environment_type": "prod",
"name": "Customer Admin",
"privileges": {
"Collaborator SAML SSO auth": [
"all"
],
"Custom OAuth profiles": [
"read"
],
"Connection Folders": [
"all"
],
"Projects": [
"read"
],
"Folders": [
"read",
"update"
],
"Connections": [
"read",
"update"
],
"Recipes": [
"read",
"create",
"update",
"delete",
"run",
"read_run_history"
]
},
"folder_ids": [
43469
]
},
{
"environment_type": "test",
"name": "Customer Admin",
"privileges": {
"Collaborator SAML SSO auth": [
"all"
],
"Custom OAuth profiles": [
"read"
],
"Connection Folders": [
"all"
],
"Projects": [
"read"
],
"Folders": [
"read",
"update"
],
"Connections": [
"read",
"update"
],
"Recipes": [
"read",
"create",
"update",
"delete",
"run",
"read_run_history"
]
},
"folder_ids": [
43468
]
}
]
}
On-prem
→
Last updated: 10/10/2024, 5:54:55 PM