# Connections

Use the following endpoints to manage connections.

# Quick reference

Type Resource Description
GET /api/connections Returns all connections and associated data.
POST /api/connections Create a connection.
PUT /api/connections/:connection_id Updates a connection.
POST /api/connections/:connection_id/disconnect Disconnects a connection.
DELETE /api/connections/:connection_id Deletes a connection.

# List connections

Returns all connections and associated data for the authenticated Workato user.

GET /api/connections

# URL parameters

Name Type Description
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/connections
      -H 'Authorization: Bearer <api_token>'

# Response

[
  {
    "application": "salesforce",
    "id": 36,
    "name": "ACME Production Salesforce connection",
    "description": null,
    "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": null,
    "folder_id": 4515,
    "parent_id": null
  },
  {
      "application": "google_sheets",
      "id": 37,
      "name": "ACME google sheet account",
      "description": null,
      "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": null,
      "folder_id": 4515,
      "parent_id": null
  }
]

# Create a connection

Create a new connection. This endpoint supports the following actions:

  • Create a shell connection
  • Create and authenticate a connection

Feature compatibility: OAuth type connections

This endpoint does not support creating and authenticating a connection for OAuth type connections. However, you can use this endpoint to create a shell connection for your OAuth connections.

POST /api/connections

# Payload

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

Name Type Description
name string
optional
Name of the connection. For example: Prod JIRA connection
provider string
optional
The application type of the connection. For example: jira
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/connections \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d  '{
            "name": "Prod JIRA connection",
            "provider": "jira",
            "folder_id": 1892,
          }'

# Connection with credentials

This creates and authenticates a connection.

curl  -X POST https://www.workato.com/api/connections \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d  '{
            "name": "Prod JIRA connection",
            "provider": "jira",
            "folder_id": 1892,
            "input": {
              "host_name": "acme.atlassian.net",
              "auth_type": "api_token",
              "email": "[email protected]",
              "apitoken": "XXXXXXXX"
            }
          }'

# Response

{
   "id":36,
   "name":"Prod JIRA connection",
   "provider":"jira",
   "authorized_at":"2023-01-26T22:53:52.528Z",
   "authorization_status":"success",
   "authorization_error":null,
   "created_at":"2023-01-26T22:53:52.532Z",
   "updated_at":"2023-01-26T22:53:52.532Z",
   "external_id":null
   "folder_id":1892,
   "parent_id":null
}

# Update a connection

Updates a connection in a non-embedded workspace.

PUT /api/connections/:connection_id

# URL parameters

Name Type Description
connection_id string
required
The ID of the connection.

# Payload

Name Type Description
name string
optional
Name of the connection. For example: 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 one of your other applications.
input object
optional
Connection parameters.

For a list of providers and connection parameters, refer to the Platform API connection parameter reference.

# Sample requests

# Update a Jira connection

curl  -X PUT https://www.workato.com/api/connections/1678 \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d  '{
            "name": "jira_connection_latest",
            "folder_id": 28940,
            "input": {
              "host_name": "acme.atlassian.net",
              "api_token_auth": "true",
              "email": "[email protected]",
              "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 an Outreach connection

curl  -X PUT https://www.workato.com/api/connections/1678 \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d  '{
            "name": "Outreach scope connection",
            "provider": "outreach",
            "input": {
              "advanced_settings": {
                "scopes": "sequences.all phoneNumbers.all"
              }
            }
          }'

# Disconnect a connection

Disconnects an active connection in a non-embedded workspace. If the connection is already disconnected, no action is taken.

POST /api/connections/:connection_id/disconnect

# URL parameters

Name Type Description
connection_id string
required
The ID of the connection.
force boolean
optional
Value must be true to forcefully disconnect an active connection used by active recipes. Defaults to false.

# Payload

No payload is expected.

# Sample request

curl -X POST https://www.workato.com/api/connections/1678/disconnect \
     -H 'Authorization: Bearer <api_token>' \
     -H 'Content-Type: application/json' \
     -d '{ "force": true }'

# Response

  • Successfully disconnected an active connection or connection already disconnected.
{
   "result": {
    "success": true,
    "status": "disconnected"
   }
}
  • Provided connection ID does not exist
{
   "message": "Not found"
}

# Delete a connection

Deletes a disconnected connection in a non-embedded workspace. If the connection is active or used by active recipes, this API request fails.

DELETE /api/connections/:connection_id

# URL parameters

Name Type Description
connection_id string
required
The ID of the connection.

# Sample request

curl  -X DELETE https://www.workato.com/api/connections/1678 \
      -H 'Authorization: Bearer <api_token>'

# Response

  • Successfully deleted a disconnected connection.
{
   "result": {
    "success": true,
    "status": "deleted"
   }
}
  • Provided connection is active
{
   "success": false,
   "status": "rejected",
   "message": "You can't delete an active connection"
}
  • Provided connection is used in active recipes
{
   "success": false,
   "status": "rejected",
   "message": "You can't delete a connection used by active recipes"
}
  • Provided connection ID does not exist
{
   "message": "Not found"
}


Last updated: 6/5/2024, 5:29:52 PM