# Workato API - Connections

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 Connections resource enables you to programmatically manage connections for Workato Embedded customer accounts.

# 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 (ex: EA2300) and the resulting ID should be URL encoded.

# Payload

Include the following properties in the request body to filter results:

Name Type Description
provider string
optional
The application type of the connection. For example: salesforce
folder_id string
optional
The ID of the project or folder containing the connection.
parent_id string
optional
The ID of the parent connection. The parent connection must be the same provider type. Learn more.
external_id string
optional
The external ID assigned to the connection, usually given to the user who owns the connection.

# 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": 22317
   }
 ]
}

# Create A Connection

Creates a connection in a customer's account. This endpoint supports the following in customer accounts:

  • Adding a shell connection, OR
  • Adding and authenticating a connection
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 (ex: EA2300) and the resulting ID should be URL encoded.

# Payload

Name Type Description
name string
optional
Name of the connection. Eg: Prod Salesforce connection
provider string
optional
The application type of the connection. For example: salesforce
parent_id string
optional
The ID of the parent connection. The parent connection must be the same provider type. Learn more.
folder_id string
optional
The ID of the project or folder containing the connection.
external_id string
optional
The external ID assigned to the connection, usually given to the user who owns the connection.
input Object
optional
Connection parameters.

For a list of providers and connection parameters, refer to the Platform API Connection Parameter Reference.

# Sample Requests

# Shell connection request

This creates a 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 with credentials

This creates and authenticates a connection.

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":22318
}

# Update A 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 (ex: EA2300) and the resulting ID should be URL encoded.
connection_id string
required
The ID of the connection.

# Payload

Name Type Description
name string
optional
Name of the connection. Ex: Prod Salesforce connection
parent_id string
optional
The ID of the parent connection. Learn more.
folder_id string
optional
The ID of the project or folder containing the connection.
external_id string
optional
An external ID assigned to the connection. This value could reference a record in another of your applications.
input object
optional
Connection parameters.

For a list of providers and connection parameters, refer to the Platform API Connection Parameter Reference.

# 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":22318
}