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

# 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, or
  • 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. Eg: 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": "smith@acme.com",
              "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
}


Last updated: 10/18/2023, 7:14:53 PM