Developer API

The Workato Developer API offers access to a wide range of Workato resources that enable you to manage recipes, connections, jobs, and more. You can use this API to automate every aspect of your Workato workspace, from deploying recipe manifests between development and production environments to rolling out new on-premises agents within your network landscape.

Base URL

The Workato API is a collection of API endpoints for interacting with Workato users, recipes, and more. Each endpoint contains the base URL and the resource path to the object.

The base URL of the API endpoint depends on the data center that you use:

• US Data Center: https://www.workato.com/api/
• EU Data Center: https://app.eu.workato.com/api/
• JP Data Center: https://app.jp.workato.com/api/
• SG Data Center: https://app.sg.workato.com/api/
• AU Data Center: https://app.au.workato.com/api/

VIRTUAL PRIVATE WORKATO (VPW) CUSTOMERS

This page provides general guidance for all Workato users. If you're a Virtual Private Workato (VPW) customer, refer to your private documentation for detailed configuration guidance specific to your instances.

Authentication

Workato API uses API tokens to authenticate requests. You can generate an API token by creating an API client under Workspace admin and assigning it both a client role and project scopes.

LEGACY API KEY DEPRECATION

Prior to API clients, Workato's API used a legacy, full-access API key and email in request headers or the query parameters to authenticate requests. Legacy API keys are deprecated as of January 1, 2024, and are no longer supported. All API requests authenticated using legacy API keys will be rejected. Learn more about migrating to API client authentication.

Provide API tokens as a bearer token

Provide your API client's API token in the request headers as a Bearer token.

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

Supported formats

Workato API supports sending request bodies with the application/json content-type. All replies are also encoded in application/json; charset=utf-8.

How to generate an API token

PERMISSION REQUIREMENTS

To create or edit API clients, you must:

• Be signed in with the root email address of the workspace, have the Admin system role, or a custom role with the API Clients privilege, located in Workspace admin.

You can generate an API token by creating an API client under Workspace admin and under the API Clients tab. Learn more about configuring API clients and roles.

HTTP response codes

• 200 Success
• 400 Bad Request
• 401 Unauthorized
• 403 Forbidden
• 404 Not Found
• 500 Server Error

200 Success

The 200 Success response indicates that the request was processed successfully by the server. The response body varies depending on the endpoint and operation performed, but it typically contains the requested data or a confirmation of the action performed.

Sample reply

{
    "success": true
}

400 Bad Request

The 400 Bad Request error indicates that the server couldn't process the request due to client-side issues. Common causes include malformed requests, invalid fields, or violations of field constraints, such as unsupported data types.

Sample reply

{
    "errors": [
        {
            "code": 400,
            "title": "No workspaces found matching the specified workspace filter conditions."
        }
    ]
}

401 Unauthorized

The 401 Unauthorized error is returned when the request lacks valid authentication credentials. Common causes include missing tokens, invalid tokens, or incorrect credentials.

Sample reply

{
    "errors": [
        {
            "code": 401,
            "title": "Unauthorized"
        }
    ]
}

403 Forbidden

The 403 Forbidden error indicates that the client is authenticated but doesn't have the necessary permissions to access the requested resource.

Sample reply

{
    "errors": [
        {
            "code": 403,
            "title": "Forbidden"
        }
    ]
}

404 Not Found

The 404 Not Found error is returned when the requested resource doesn't exist or can't be found. This can occur if the URL is incorrect or the resource has been deleted.

Sample reply

{
    "errors": [
        {
            "code": 404,
            "title": "Not found"
        }
    ]
}

500 Server Error

The 500 Server Error code indicates that the server encountered an unexpected condition that prevented it from fulfilling the request. This error is usually caused by server-side issues.

Sample reply

{
    "errors": [
        {
            "code": 500,
            "title": "Server error",
            "detail": "3188c2d0-29a4-4080-908e-582e7ed82580"
        }
    ]
}