# Connections

Use the following endpoints to manage connections.

# Quick reference

Type	Resource	Description
GET	/api/connections	Lists connections belonging to a user.
POST	/api/connections	Creates 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

# Query 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.
includes[]	array of strings optional	Specifies additional fields to include in the response. Accepts `tags` as a value. If `tags` is supplied in the request, the response includes a `tags` field for each connection. This field contains an array of zero or more tag handles (strings).

# Sample request

curl  -X GET https://www.workato.com/api/connections?includes[]=tags
      -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,
    "connection_lost_at": null,
    "connection_lost_reason": null,
    "parent_id": null,
    "tags": [
      "tag-ANgeffPL-3gxQwA"
    ]
  },
  {
    "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,
    "connection_lost_at": null,
    "connection_lost_reason": null,
    "parent_id": null,
    "tags": 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.

# 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
Update an Outreach connection

# 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.

{
    "success": true,
    "status": "disconnected"

}

Provided connection ID does not exist

{
   "message": "Not found"
}

# Delete a connection

Deletes a connection in a non-embedded workspace. This method deletes active (authenticated) and disconnected connections. If the connection is used by active recipes or as an Audit log streaming destination, 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>'

# Responses

Successful deletion of an active or disconnected connection
Connection is used in active recipes
Connection is used for Audit log streaming
Connection ID doesn't exist

# Successful deletion of an active or disconnected connection

When you successfully delete an active (authenticated) or disconnected connection, this endpoint returns the following response:

{
    "success": true,
    "status": "deleted"
}

# Connection is used in active recipes

When you try to delete a connection used by an active recipe, this request fails, and the endpoint returns the following response:

{
   "success": false,
   "status": "rejected",
   "message": "You can't delete a connection used by active recipes"
}

# Connection is used for Audit log streaming

When you try to delete a connection used as an Audit log streaming destination, this request fails, and the endpoint returns the following response:

{
    "success": false,
    "status": "rejected",
    "message": "You can't delete a connection used by audit log streaming"
}

# Connection ID doesn't exist

If you provide a connection ID that doesn't exist in your workspace, this request fails, and the endpoint returns the following response:

{
   "message": "Not found"
}

Last updated: 10/9/2024, 3:09:56 PM