# Connections

Use the following endpoints to manage connections.

# Rate limits

Connections resources have the following rate limits:

Type	Resource	Limit
GET	List connections: /api/connections	60 requests per minute
All	All other Connections endpoints	1 request per second

# 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).
updated_after	string optional	Filter the list of connections to include only those updated after the date and time you specify. The date and time must be provided in ISO 8601 format according to the following pattern: `YYYY-MM-DDTHH:MM:SSZ`.

# 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

AUTHORIZATION CODE GRANT CONNECTIONS

The Workato API allows you to create OAuth 2.0 connections. However, authorization code grant connections require that you add an oauth_token_pair object, which contains both an access token and a refresh token as strings. You can create a shell connection in cases where you don't have an access token and refresh token.

Refer to the Connection parameters reference page for more information.

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 conditionally required	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.
shell_connection	boolean optional	Specifies whether the connection is a shell connection or an authenticated connection. Defaults to `false` if not specified. If `shell_connection` is `false`, credentials are passed, and the connection is tested and established. If `shell_connection` is `true`, credentials are passed, but the connection isn't tested or established, and additional actions are required for authentication.
input	Object optional	Connection parameters. For a list of providers and connection parameters, refer to the Platform API connection parameter reference.

FOLDER_ID IS CONDITIONALLY REQUIRED

The folder_id parameter is required if the target workspace's Home assets folder has been converted to a project. Refer to the Projects page's Home assets project section for more information.

# 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.
shell_connection	boolean optional	Specifies whether the connection is a shell connection or an authenticated connection. Defaults to `false` if not specified. If `shell_connection` is `false`, credentials are passed, and the connection is tested and established. If `shell_connection` is `true`, credentials are passed, but the connection isn't tested or established, and additional actions are required for authentication.
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/16/2025, 9:32:50 PM