# Connections

Use the following endpoints to retrieve and create the connections that belong to a Workato Embedded customer account. All API endpoints listed here requires oem_vendor privilege. Talk to your Workato representative to enable this privilege in your account.

# Quick reference

Type Resource Description
GET /api/managed_users/:managed_user_id/connections Returns a list of connections in Workato Embedded user's account.
POST /api/managed_users/:id/connections Allows the Workato Embedded partner to add a shell connection in a customer's account.
PUT /api/managed_users/:id/connections/:connection_id Updates a connection in a customer account.

# List connections

Returns all connections and associated data for the Workato Embedded customer account.

GET /api/managed_users/:managed_user_id/connections

# URL parameters

Name Type Description
managed_user_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.
folder_id string
optional
Folder ID of the connection.
parent_id string
optional
Parent ID of the connection. Connection must be of the same provider.
external_id string
optional
External identifier usually given to the user who owns the connection.
include_runtime_connections string
optional
When "true" is supplied, all runtime user connections are also returned.

# Sample request

curl  -X GET https://www.workato.com/api/managed_users/98178/connections \
      -H 'x-user-email: <email>' \
      -H 'x-user-token: <token>'

# Response

{
 "result": [
   {
     "id": 36,
     "name": "ACME Production Salesforce connection",
     "provider": "salesforce",
     "authorized_at": "2015-05-26T22:53:52.528Z",
     "authorization_status": "success",
     "authorization_error": null,
     "created_at": "2015-05-26T22:53:52.532Z",
     "updated_at": "2015-05-26T22:53:52.532Z",
     "external_id": "U12904",
     "folder_id": 4515,
     "parent_id": 22316
   },
   {
       "id": 37,
       "name": "ACME google sheet account",
       "provider": "google_sheets",
       "authorized_at": "2015-05-26T22:53:52.528Z",
       "authorization_status": "success",
       "authorization_error": null,
       "created_at": "2015-05-26T22:53:52.532Z",
       "updated_at": "2015-05-26T22:53:52.532Z",
       "external_id": "U12904",
       "folder_id": 4515,
       "parent_id": 22316
   }
 ]
}

# Create connection

Allows the Workato Embedded partner to:

  • Add a shell connection in a customer's account OR
  • Add and authenticate a connection in a customer's account
POST /api/managed_users/:managed_user_id/connections

# URL parameters

Name Type Description
managed_user_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.

# Body

Name Type Description
name string
optional
Name of the connection. Eg: 'Prod Salesforce connection'
provider string
required
Connector identifier. Eg: 'salesforce'
input Object
optional
Connection parameters.
folder_id string
optional
Folder ID of the connection.
parent_id string
optional
Parent ID of the connection. Connection must be of the same provider.
external_id string
optional
External identifier usually given to the user who owns the connection.

For a list of providers and connection parameters, please view this document.

# Sample request

# Shell connection request

This creates the connection in a 'Disconnected' state.

curl  -X POST https://www.workato.com/api/managed_users/98178/connection \
      -H 'x-user-email: <email>' \
      -H 'x-user-token: <token>' \
      -H 'Content-Type: application/json' \
      -d  '{
            "name": "jira_connection",
            "provider": "jira",
            "folder_id": 1892,
            "external_id": "128904"
          }'
# Connection request with credentials

Authenticates the connection (API token authentication).

curl  -X POST https://www.workato.com/api/managed_users/98178/connection \
      -H 'x-user-email: <email>' \
      -H 'x-user-token: <token>' \
      -H 'Content-Type: application/json' \
      -d  '{
            "name": "jira_connection",
            "provider": "jira",
            "input": {
              "host_name": "acme.atlassian.net",
              "api_token_auth": "true",
              "email": "smith@acme.com",
              "apitoken": "XXXXXXXX"
            }
          }'

# Response

{
 "id": 36,
 "name": "jira_connection",
 "provider": "jira",
 "authorized_at": "2015-05-26T22:53:52.528Z",
 "authorization_status": "success",
 "authorization_error": null,
 "created_at": "2015-05-26T22:53:52.532Z",
 "updated_at": "2015-05-26T22:53:52.532Z",
 "external_id": "U12904",
 "folder_id": 4515,
 "parent_id": 22316
}

# Update connection

Updates a connection in a customer account.

PUT /api/managed_users/:managed_user_id/connections/:connection_id

# URL parameters

Name Type Description
managed_user_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.
connection_id string
required
ID of the connection

# Body

Name Type Description
name string
optional
Name of the connection. Eg: 'Prod Salesforce connection'
input Object
optional
Connection parameters.
folder_id string
optional
Folder ID of the connection.
parent_id string
optional
Parent ID of the connection. Connection must be of the same provider.
external_id string
optional
External identifier usually given to the user who owns the connection.

For a list of providers and connection parameters, please view this document.

# Sample request

curl  -X PUT https://www.workato.com/api/managed_users/98178/connections/1678 \
      -H 'x-user-email: <email>' \
      -H 'x-user-token: <token>' \
      -d  '{
            "name": "jira_connection_latest",
            "folder_id": 28940,
            "input": {
              "host_name": "acme.atlassian.net",
              "api_token_auth": "true",
              "email": "smith@acme.com",
              "apitoken": "XXXXXXXX"
            }
          }'

# Response

{
 "id": 36,
 "name": "jira_connection",
 "provider": "jira",
 "authorized_at": "2015-05-26T22:53:52.528Z",
 "authorization_status": "success",
 "authorization_error": null,
 "created_at": "2015-05-26T22:53:52.532Z",
 "updated_at": "2015-05-26T22:53:52.532Z",
 "external_id": "U12904",
 "folder_id": 4515,
 "parent_id": 22316
}