# Manage customer accounts

All API endpoints listed here are Workato Embedded Vendor APIs and require the oem_vendor privilege. Talk to your Workato representative to enable this privilege in your account.

# Quick reference

Type Resource Description
POST /api/managed_users Create a customer account.
PUT /api/managed_users/:id Update a customer account.
DELETE /api/managed_users/:id Delete a customer account.
GET /api/managed_users/:id Get a customer account.
GET /api/managed_users/ List all customer accounts.
GET /api/managed_users/:id/members List members in a customer account.
GET /api/managed_users/:id/members/:member_id Get a member in a customer account.
POST /api/managed_users/:id/members Add a member to a customer account.
PUT /api/managed_users/:id/members/:member_id Update a member in a customer account.
DELETE /api/managed_users/:id/members/:member_id Remove a member from a customer account.
GET /api/managed_users/:id/connections List connections in a customer account.
GET /api/managed_users/usage Get task usage of all customer accounts by month.
PUT /api/managed_users/:id/upgrade Deprecated. Upgrade customer account.
PUT /api/managed_users/:id/downgrade Deprecated. Downgrade customer account.
POST /api/managed_users/:id/member Deprecated. Add member to customer account.
DELETE /api/managed_users/:id/member Deprecated. Remove member from customer account.

Deprecated endpoints

Deprecated endpoints will continue to work but are not supported with the newest updates going forward.

# Create customer account

Create a new Workato Embedded customer account.

POST /api/managed_users

# Payload

Name Type Description
name string
required
Full name of the user.
notification_email string
required
Email for error notifications.
plan_id string
optional
Plan id. Default plan id is used when not provided.
external_id string
optional
External identifier for the Workato Embedded customer.
origin_url string
optional
Applies to embedded Workato Embedded account customers. Provide a value if the embedded IFrame is hosted in a non-default origin page. For example, customer specifc custom domains. Defaults to the origin configured at the account level.
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.

# Sample request (Workato authentication)

curl  -X POST https://www.workato.com/api/managed_users \
      -H 'x-user-email: <email>' \
      -H 'x-user-token: <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"
              }
          }'

# Sample request (SAML SSO, metadata URL)

curl  -X POST https://www.workato.com/api/managed_users \
      -H 'x-user-email: <email>' \
      -H 'x-user-token: <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/exk3ar7z0drZQFDpK696/sso/saml/metadata"
            }
          }'

# Sample request (SAML SSO, X509 cert)

curl  -X POST https://www.workato.com/api/managed_users \
      -H 'x-user-email: <email>' \
      -H 'x-user-token: <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"
              }
          }'

# Response

{
    "id": 14242,
    "external_id": "128490",
    "name": "B-max",
    "notification_email": "admin@bmax.com",
    "plan_id": "business_yearly",
    "origin_url": 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"
    }
}

# Update customer account

PUT /api/managed_users/:id

Update an existing Workato Embedded customer account's:

  • 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 Workato embedded, use this endpoint to update the custom origin URL of a specific customer

# URL parameters

Name Type Description
id string
required
Workato 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 notifications.
external_id string
optional
External identifier for the Workato Embedded customer.
origin_url string
optional
Applies to embedded Workato Embedded account customers. Provide a value if the embedded IFrame is hosted in a non-default origin page(For example, customer specifc custom domains etc). Defaults to the origin configured at the account level.
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.
current_billing_period_start string
optional
Set the current billing start date. Date and time should be given in ISO 8601 format.

# Sample request

curl  -X PUT https://www.workato.com/api/managed_users/3498583 \
      -H 'x-user-email: <email>' \
      -H 'x-user-token: <token>' \
      -H 'Content-Type: application/json' \
      -d '{,
            "notification_email": "kevinl+workatodevops@acme.com",
            "whitelisted_apps": ["salesforce", "netsuite"],
            "auth_settings": {
              "type": "saml_sso",
              "provider": "okta",
              "metadata_url": "https://workato.okta.com/app/exk3ar7z0drZQFDpK696/sso/saml/metadata"
            }
          }'

# Response

{
    "id": 3498583,
    "external_id": "",
    "name": "Kevin K Leary",
    "notification_email": "kevinl+workatodevops@acme.com",
    "plan_id": "task_plan_1",
    "origin_url": 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/exk3ar7z0drZQFDpK696/sso/saml/metadata"
    },
    "time_zone": "Alaska"
}

# Delete customer account

Proceed with caution!

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

Delete a Workato Embedded customer account.

DELETE /api/managed_users/:id

# URL parameters

Name Type Description
id string
required
Workato 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 'x-user-email: <email>' \
      -H 'x-user-token: <token>' \
      -H 'Content-Type: application/json' \

# Response

{
    "success": true
}

# Get customer account

Get details about a Workato Embedded customer account.

GET /api/managed_users/:id

# URL parameters

Name Type Description
id string
required
Workato 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 'x-user-email: <email>' \
      -H 'x-user-token: <token>'

# Response

{
    "id": 4243,
    "external_id": "",
    "name": "Abstergo Industries",
    "notification_email": "ann@abstergo.com",
    "plan_id": "tbp_wrike_monthly_1",
    "whitelisted_apps": ["salesforce", "netsuite"],
    "origin_url": 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"
}

# 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/
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 'x-user-email: <email>' \
      -H 'x-user-token: <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",
            "notification_email": "ann@abstergo.com",
            "whitelisted_apps": ["salesforce", "netsuite"],
            "plan_id": "plan_tier1",
            "origin_url": 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
        },
        {
            "id": 4772,
            "external_id": "101",
            "name": "Carly's Company",
            "notification_email": "carly.frederick@w.com",
            "whitelisted_apps": ["salesforce", "netsuite"],
            "plan_id": "business_yearly",
            "origin_url": 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
        }
      ]
}

# Get list of customer account members

Get 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
Workato 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 'x-user-email: <email>' \
      -H 'x-user-token: <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
Workato 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 'x-user-email: <email>' \
      -H 'x-user-token: <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 Workato Embedded customer account.

POST /api/managed_users/:id/members

# URL parameters

Name Type Description
id string
required
Workato 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
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 POST https://www.workato.com/api/managed_users/27819/members \
      -H 'x-user-email: <email>' \
      -H 'x-user-token: <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

Update a member in an existing Workato Embedded customer account. Note: Only members added via API can be updated this way.

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

# URL parameters

Name Type Description
id string
required
Workato 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 'x-user-email: <email>' \
      -H 'x-user-token: <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 a Workato 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
Workato 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 'x-user-email: <email>' \
      -H 'x-user-token: <token>' \
      -H 'Content-Type: application/json' \

# Response

{
  "id": 3485434779
}

# List customer connections

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

GET /api/managed_users/:id/connections

# URL parameters

Name Type Description
id string
required
Workato 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 'x-user-email: <email>' \
      -H 'x-user-token: <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 Workato 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 still 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 'x-user-email: <email>' \
      -H 'x-user-token: <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"
   }
}