Connections

The Connections resource enables you to programmatically manage connections for Embedded customers.

ENDPOINT AVAILABILITY

The endpoints in this guide are Embedded APIs and require an Embedded workspace. Contact your Workato representative for more information.

Rate limits

Connection resources have the following rate limits:

Quick reference

Type	Resource	Description
GET	/api/managed_users/:managed_user_id/connections /:adapter_name/input_schema	Returns input schema based on a connection's input.
GET	/api/managed_users/:managed_user_id/connections	Returns a list of connections in Embedded user's account.
POST	/api/managed_users/:id/connections	Allows the 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 workspace.
POST	/api/managed_users/:id/connections/:connection_id/disconnect	Disconnects a connection in a customer workspace.
DELETE	/api/managed_users/:id/connections/:connection_id	Deletes a connection in a customer workspace.

Get connection endpoint

Returns input schema based on a connection's input. It returns both the base input schema, part of the extended_settings_schema that activates because of the connection's input. This endpoint works at a connection level of Workato.

shell

GET /api/managed_users/:managed_user_id/connections/:connection_id/input_schema

Refer to Get connector endpoint for information about the get connector endpoint.

URL parameters

Name	Type	Description
managed_user_id	string required	Embedded customer Account ID or External ID. External IDs must have the prefix 'E' and be URL-encoded. For example, 'EA2300'.
connection_id	string required	The connection ID for which you plan to get the base input schema.

Sample request

shell

curl  -X GET https://www.workato.com/api/managed_users/97/connections/1987654/input_schema \
      -H 'Authorization: Bearer <api_token>'

Response

JSON

{
  "result": [
    {
      "control_type": "text",
      "label": "Api key",
      "disable_formula": true,
      "optional": false,
      "type": "string",
      "name": "apiKey"
    }
  ]
}

List connections

Returns all connections and associated data for the Embedded customer workspace.

shell

GET /api/managed_users/:managed_user_id/connections

URL parameters

Name	Type	Description
managed_user_id	string required	Embedded customer ID/external ID. External ID must be prefixed with an `E` (ex: `EA2300`) and the resulting ID should be URL encoded.

Query parameters

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.
project_id	string optional	The ID of the project containing the connection.
external_id	string optional	The external ID assigned to the connection, 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

shell

curl  -X GET https://www.workato.com/api/managed_users/98178/connections?includes[]=tags \
      -H 'Authorization: Bearer <api_token>'

Response

json

{
 "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,
     "identity": null,
     "connection_lost_at": null,
     "connection_lost_reason": null,
     "parent_id": 22316,
     "project_id": 12314295,
     "tags": [
        "tag-ANgeffPL-3gxQwA"
      ]
   },
   {
     "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,
     "identity": null,
     "connection_lost_at": "2024-06-01T12:00:00Z",
     "connection_lost_reason": "network_failure",
     "parent_id": 22317,
     "project_id": 12314296,
     "tags": null
   },
   {
     "id": 51234,
     "name": "ACME Quickbooks account",
     "provider": "quickbooks",
     "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,
     "identity": "acme@workato.com/1029384756102938",
     "connection_lost_at": null,
     "connection_lost_reason": null,
     "parent_id": 22317,
     "project_id": 12314297,
     "tags": [
        "tag-ANgeffPL-3gxQwA"
      ]
   }
 ]
}

RETRIEVE QUICKBOOKS REALM ID

Retrieve your company's Quickbooks Realm ID using the List connections API. Disconnect and reconnect your Quickbooks connection in Workato before calling the API to ensure the latest information is retrieved. The API returns the Realm ID in the identity field of the response, following your email address. In the preceding example, ACME's Realm ID is 1029384756102938. For other connections, the identity field is returned as null.

Refer to the SDK identity lambda documentation for more details on setting up the identity field. The lambda’s output value is returned in the identity field of the list connections API.

Create a connection

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

Adding a shell connection, OR
Adding and authenticating a connection

OAUTH CONNECTIONS

The Workato API allows you to create OAuth 2.0 connections. However, connections types that would normally redirect you to a sign-in screen, such as oauth or oauth2_auth_code_grant, require an oauth_token_pair object containing an access token and a refresh token. Client credentials grant connections don't require an oauth_token_pair object. 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/managed_users/:managed_user_id/connections

URL parameters

Name	Type	Description
managed_user_id	string required	Embedded customer 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 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 REQUIRED STARTING MAY 7, 2026

Starting May 7, 2026, the folder_id parameter is required on this endpoint. The value must reference a project or folder other than the Home assets folder. Requests that omit folder_id or target the Home assets folder will return an error.

Shell connection request

This creates a connection in a Disconnected state.

shell

curl  -X POST https://www.workato.com/api/managed_users/98178/connections \
      -H 'Authorization: Bearer <api_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.

shell

curl  -X POST https://www.workato.com/api/managed_users/98178/connections \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d  '{
            "name": "jira_connection",
            "provider": "jira",
            "folder_id": 1892,
            "input": {
              "host_name": "acme.atlassian.net",
              "api_token_auth": "true",
              "email": "smith@acme.com",
              "apitoken": "XXXXXXXX"
            }
          }'

Response

json

{
   "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":1892,
   "parent_id":22318,
   "connection_lost_at": null,
   "connection_lost_reason": null
}

Update a connection

Updates a connection in a customer workspace.

PUT /api/managed_users/:managed_user_id/connections/:connection_id

URL parameters

Name	Type	Description
managed_user_id	string required	Embedded customer 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.
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

shell

curl  -X PUT https://www.workato.com/api/managed_users/98178/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": "smith@acme.com",
              "apitoken": "XXXXXXXX"
            }
          }'

Response

json

{
   "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,
   "connection_lost_at": null,
   "connection_lost_reason": null
}

Update an Outreach connection

shell

curl  -X PUT https://www.workato.com/api/managed_users/98178/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 customer workspace. If the connection is already disconnected, then no action is taken.

POST /api/managed_users/:managed_user_id/connections/:connection_id/disconnect

URL parameters

Name	Type	Description
managed_user_id	string required	Embedded customer 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.
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

shell

curl  -X POST https://www.workato.com/api/managed_users/98178/connections/1678/disconnect?force=true \
      -H 'Authorization: Bearer <api_token>'

Response

Successfully disconnected an active connection or connection already disconnected.

json

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

Provided connection id does not exist

json

{
   "message": "Not found"
}

Delete a connection

Deletes a connection in a customer workspace. This method deletes active (authenticated) and disconnected connections. If the connection is used by active recipes, this API request fails.

DELETE /api/managed_users/:managed_user_id/connections/:connection_id

URL parameters

Name	Type	Description
managed_user_id	string required	Embedded customer 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.

Sample request

shell

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

Responses

Successful deletion of an active or disconnected connection
Connection is used in active recipes
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:

json

{
    "result": {
        "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:

json

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

Connection ID doesn't exist

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

json

{
   "message": "Not found"
}

Last updated:

Connections ​

Rate limits ​

Quick reference ​

Get connection endpoint ​

URL parameters ​

Sample request ​

Response ​

List connections ​

URL parameters ​

Query parameters ​

Sample request ​

Response ​

Create a connection ​

URL parameters ​

Payload ​

Sample requests ​

Shell connection request ​

Connection with credentials ​

Response ​

Update a connection ​

URL parameters ​

Payload ​

Sample requests ​

Update a Jira connection ​

Response ​

Update an Outreach connection ​

Disconnect a connection ​

URL parameters ​

Payload ​

Sample request ​

Response ​

Delete a connection ​

URL parameters ​

Sample request ​

Responses ​

Successful deletion of an active or disconnected connection ​

Connection is used in active recipes ​

Connection ID doesn't exist ​

Connections

Rate limits

Quick reference

Get connection endpoint

URL parameters

Sample request

Response

List connections

URL parameters

Query parameters

Sample request

Response

Create a connection

URL parameters

Payload

Sample requests

Shell connection request

Connection with credentials

Response

Update a connection

URL parameters

Payload

Sample requests

Update a Jira connection

Response

Update an Outreach connection

Disconnect a connection

URL parameters

Payload

Sample request

Response

Delete a connection

URL parameters

Sample request

Responses

Successful deletion of an active or disconnected connection

Connection is used in active recipes

Connection ID doesn't exist