Product UpdatesStatus PageWorkato Academy
English
Get a trial
Developer API
Resources

# On-premise API

Workato API allows you to work with on-prem groups and on-prem agents through the API.

# Rate limits

On-prem resources have the following rate limits:

Type Resource Limit
AllAll On-prem endpoints60 requests per minute

# Quick reference

Type Resource Description
GET /api/on_prem_groups List on-prem groups.
POST /api/on_prem_groups Create on-prem group.
GET /api/on_prem_groups/:id Get on-prem group details.
PUT /api/on_prem_groups/:id Update on-prem group.
DELETE /api/on_prem_groups/:id Delete an on-prem group.
GET /api/on_prem_groups/:id/status Get on-prem group status.
GET /api/on_prem_agents List on-prem agents.
POST /api/on_prem_agents Create on-prem agent.
GET /api/on_prem_agents/:id Get on-prem agent details.
PUT /api/on_prem_agents/:id Update on-prem agent.
DELETE /api/on_prem_agents/:id Delete on-prem agents.
GET /api/on_prem_agents/:id/status Get on-prem agent status.
GET /api/on_prem_agents/search Search for on-prem agent.
GET /api/on_prem_agents/:id/activation_code Get on-prem agent activation code.

# List on-prem groups

List all on-prem groups in your workspace.

GET /api/on_prem_groups

# Sample request

curl -X GET 'https://www.workato.com/api/on_prem_groups' \
     -H 'Authorization: Bearer <api_token>' \

# Response

[
  {
    "id": 16803,
    "name": "CRM server",
    "created_at": "2017-09-21T01:51:45.954-07:00",
    "in_use": true,
    "use_managed_connection": true,
    "config_version": 9,
    "logs_enabled": false,
    "whitelisted_ips": [
      "198.51.100.10",
      "192.0.2.0/24"
    ]
  }
]

# Create on-prem group

Create an on-prem group.

POST /api/on_prem_groups

# Payload

Name Type Description
name string
required		 The on-prem group's name.
use_managed_connection boolean
optional		 Set to true to configure the on-prem group using a cloud profile or false to configure each agent manually using a config.yml file. Defaults to false if not specified.
settings_attributes[whitelisted_ips] array of strings
optional		 Defines IPs to whitelist for the on-prem group.

# Sample request

curl -X POST 'https://www.workato.com/api/on_prem_groups' \
     -H 'Authorization: Bearer <api_token>' \
     -H 'Content-Type: application/json' \
     -d '{
          "name":"CRM server",
          "use_managed_connection": true,
          "settings_attributes": { 
            "whitelisted_ips": [
              "198.51.100.10",
              "192.0.2.0/24"
            ]
          }
         }'

# Response

[
  {
    "id": 16803,
    "name": "CRM server",
    "created_at": "2017-09-21T01:51:45.954-07:00",
    "in_use": false,
    "use_managed_connection": true,
    "config_version": null,
    "logs_enabled": false,
    "whitelisted_ips": [
      "198.51.100.10",
      "192.0.2.0/24"
    ]
  }
]

# Get on-prem group details

Get details about an on-prem group.

GET /api/on_prem_groups/:id

# URL parameters

Name Type Description
id integer
required		 The ID of the on-prem group to retrieve.

# Sample request

curl -X GET 'https://www.workato.com/api/on_prem_groups/16803' \
     -H 'Authorization: Bearer <api_token>' \

# Response

[
  {
    "id": 16803,
    "name": "CRM server",
    "created_at": "2017-09-21T01:51:45.954-07:00",
    "in_use": false,
    "use_managed_connection": false,
    "config_version": null,
    "logs_enabled": false,
    "whitelisted_ips": [
        "198.51.100.10",
        "192.0.2.0/24"
    ]
  }
]

# Update on-prem group

Update an on-prem group.

PUT /api/on_prem_groups/:id

# URL parameters

Name Type Description
id integer
required		 The on-prem group's ID.

# Payload

Name Type Description
name string
optional		 The on-prem group's name.
settings_attributes[whitelisted_ips] array of strings
optional		 Defines IPs to whitelist for the on-prem group.

# Sample request

curl -X PUT 'https://www.workato.com/api/on_prem_groups/16803' \
     -H 'Authorization: Bearer <api_token>' \
     -H 'Content-Type: application/json' \
     -d '{
          "name":"CRM server",
          "settings_attributes": { 
            "whitelisted_ips": [
              "198.51.100.10",
              "192.0.2.0/24"
            ]
          }
         }'

# Response

[
  {
    "id": 16803,
    "name": "CRM server",
    "created_at": "2017-09-21T01:51:45.954-07:00",
    "in_use": false,
    "use_managed_connection": false,
    "config_version": null,
    "logs_enabled": false,
    "whitelisted_ips": [
      "198.51.100.10",
      "192.0.2.0/24"
    ]
  }
]

# Delete on-prem group

Delete an on-prem group and the on-prem agents it contains.

DELETE /api/on_prem_groups/:id

# URL parameters

Name Type Description
id integer
required		 The on-prem group's ID.

# Sample request

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

# Response

{
  "success": true
}

# Get on-prem group status

Get the status of an on-prem group.

GET /api/on_prem_groups/:id/status

# URL parameters

Name Type Description
id integer
required		 The on-prem group's ID.

# Sample request

curl -X GET 'https://www.workato.com/api/on_prem_groups/16805/status' \
     -H 'Authorization: Bearer <api_token>' \

# Response

{
  "agent_count": 4,
  "active_agent_count": 3,
  "profiles": [
    {
      "name": "CRM-Oracle",
      "provider": "oracle",
      "type": "Database",
      "connections": [
        {
          "id": 440724,
          "name": "Oracle CRM DB"
        }
      ]
    }
  ]
}

# List on-prem agents

List all on-prem agents in your workspace.

GET /api/on_prem_agents

# Sample request

curl -X GET 'https://www.workato.com/api/on_prem_agents' \
     -H 'Authorization: Bearer <api_token>' \

# Response

[
  {
    "id": 12233,
    "on_prem_group_id": 16803,
    "name": "primary agent",
    "cn": "134fd7acd89cf5b8b96deea4870d413d:12233",
    "os": "windows",
    "installation_method": null,
    "awaiting_setup": false,
    "enabled": true,
    "last_seen_version": "25.0",
    "created_at": "2024-12-10T13:20:03.330-08:00",
    "updated_at": "2025-05-12T13:03:23.754-07:00",
    "state": "connected",
    "activated": true
  }
]

# Create on-prem agent

Create an on-prem agent.

POST /api/on_prem_agents

# Payload

Name Type Description
name string
required		 The on-prem agent's name.
on_prem_group_id integer
required		 The on-prem group's ID. You can retrieve group IDs from the List on-prem groups endpoint's response.
os string
optional		 The server's operating system.
awaiting_setup boolean
optional		 Set to true to create the agent in the awaiting_setup state. Set to false to skip agent setup and get its status right away. Defaults to true if not specified.
enabled boolean
optional		 Set to true to enable the agent or false to disable it.

# Sample request

curl -X POST 'https://www.workato.com/api/on_prem_agents' \
     -H 'Authorization: Bearer <api_token>' \
     -H 'Content-Type: application/json' \
     -d '{
          "name": "US-west-1",
          "on_prem_group_id": 50,
          "os": "windows",
          "awaiting_setup": false
         }'

# Response

[
  {
    "id": 12233,
    "on_prem_group_id": 50,
    "name": "US-west-1",
    "cn": "134fd7acd89cf5b8b96deea4870d413d:12233",
    "os": "windows",
    "installation_method": null,
    "awaiting_setup": false,
    "enabled": true,
    "last_seen_version": null,
    "created_at": "2025-06-24T12:37:49.824-07:00",
    "updated_at": "2025-06-24T12:37:49.886-07:00",
    "state": "connected",
    "activated": false
  }
]

# Get on-prem agent details

Get the details of an on-prem agent.

GET /api/on_prem_agents/:id

# URL parameters

Name Type Description
id integer
required		 The on-prem agent's ID.

# Sample request

curl -X GET 'https://www.workato.com/api/on_prem_agents/12233' \
     -H 'Authorization: Bearer <api_token>' \

# Response

[
  {
    "id": 12233,
    "on_prem_group_id": 16803,
    "name": "primary agent",
    "cn": "134fd7acd89cf5b8b96deea4870d413d:12233",
    "os": "windows",
    "installation_method": null,
    "awaiting_setup": true,
    "enabled": true,
    "last_seen_version": null,
    "created_at": "2025-06-24T12:37:49.824-07:00",
    "updated_at": "2025-06-24T12:37:49.886-07:00",
    "state": "awaiting_setup",
    "activated": false
  }
]

# Update on-prem agent

Update an on-prem agent.

PUT /api/on_prem_agents/:id

# URL parameters

Name Type Description
id integer
required		 The on-prem agent's ID.

# Payload

Name Type Description
name string
optional		 The on-prem agent's name.
os string
optional		 The server's operating system.
on_prem_group_id integer
optional		 The on-prem group's ID. You can retrieve group IDs from the List on-prem groups endpoint's response.
enabled boolean
optional		 Set to true to enable the agent or false to disable it.

# Sample request

curl -X PUT 'https://www.workato.com/api/on_prem_agents/49026' \
     -H 'Authorization: Bearer <api_token>' \
     -H 'Content-Type: application/json' \
     -d '{
           "name": "primary agent"
         }'

# Response

[
  {
    "id": 49026,
    "on_prem_group_id": 32109,
    "name": "primary agent",
    "cn": "1ee944db3b24d7c19dfe4685c49b77a4:49026",
    "os": "windows",
    "installation_method": null,
    "awaiting_setup": false,
    "enabled": true,
    "last_seen_version": "27.0",
    "created_at": "2025-03-27T08:18:49.641-07:00",
    "updated_at": "2025-05-12T13:26:36.731-07:00",
    "state": "connected",
    "activated": true
  }
]

# Delete on-prem agent

Delete an on-prem agent.

DELETE /api/on_prem_agents/:id

# URL parameters

Name Type Description
id integer
required		 The on-prem agent's ID.

# Sample request

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

# Response

{
  "success": true
}

# Get on-prem agent status

Get the status of an on-prem agent.

GET /api/on_prem_agents/:id/status

# URL parameters

Name Type Description
id integer
required		 The on-prem agent's ID.

# Sample request

curl -X GET 'https://www.workato.com/api/on_prem_agents/12233/status' \
     -H 'Authorization: Bearer <api_token>' \

# Response

{
  "active": true
}

# Search for on-prem agent by common name

Search on-prem agents by their common name.

GET /api/on_prem_agents/search

# URL parameters

Name Type Description
cn string
optional		 The common name of the on-prem agent to retrieve. Omit this parameter to return all agents.

# Sample request

curl -X GET 'https://www.workato.com/api/on_prem_agents/search' \
     -H 'Authorization: Bearer <api_token>' \
     -H 'Content-Type: application/json' \
     -d  '{
             "cn": "134fd7acd89cf5b8b96deea4870d413d:12233"
          }'

# Response

[
  {
    "id": 12233,
    "on_prem_group_id": 16803,
    "name": "primary agent",
    "cn": "134fd7acd89cf5b8b96deea4870d413d:12233",
    "os": "windows",
    "awaiting_setup": false,
    "enabled": true
  }
]

# Get on-prem agent activation code

Get an activation code for an on-prem agent.

GET /api/on_prem_agents/:id/activation_code

# URL parameters

Name Type Description
id integer
required		 The on-prem agent's ID.

# Sample request

curl -X GET 'https://www.workato.com/api/on_prem_agents/12233/activation_code' \
     -H 'Authorization: Bearer <api_token>' \

# Response

[
  {
    "code": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJiMjY3MTA4NTU5NDBmMGFjYTVmNDYyMTFhNWYxMmJiNzo2MDg3MCIsImlhdCI6MTc0ODcyNTU5OSwiZXhwIjoxNzQ4NzI5MTk5LCJhZ2VudCI6NjA4NzAsImd3Ijoic2czLndvcmthdG8uY29tfHNnNC53b3JrYXRvLmNvbSJ9.JCcQ0NCetvIjP9xJJ1BIUAxmE9ImuNvtUJLNIazICiQg61RlSz2YJHywhbSXvakjjB77L7ZPydo43Rs_iiWiWRr5atk8iHvZlnfAKL_338-nFxmSkN-Ms7sL-fguNdQaO-DgkkZubAJ-qP8a34VKJ6QYA3c3SaixoNfnukKan0mUySTz7wQsVxU4C0Ff0R42AGO9CjKxYRobeBr_QgLJm6PtSUN5J6JkWGpyg9jTHJEpsFPDLBzJ0u7O7HkDP_onF4wdrraJ7_5BSn04ZllXw6oIwTbMWq1ncqhYHs0ZXNnv3efXF4L0tzgSkekdz-YasqojNSo0wzfpV0W_3vq_Mg"
  }
]
← List identity provider user groups
Projects →


Last updated: 3/19/2026, 10:57:00 PM

On this page