API Clients

API Clients allow you to enforce security best practices by creating multiple clients that have configurable access to each endpoint. Furthermore, these requests using API clients will require only a single header for authentication. Read on more to understand how you can migrate to API clients to improve your organisation's security posture.

About legacy full access API keys

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. This will continue to be supported with your legacy migrated API client that represents your API key and email. We strongly recommend migrating over to API Clients for authentication to Workato APIs. Learn more

If this legacy API client is deleted, your API key and email cannot be recovered and requests using this API key and email will be rejected.

API Client benefits

Workato's developer and embedded APIs allow you to automate all aspects of your Workato workspace - from deploying recipe manifests from development to production or deploying new on-prem agents within your network landscape. API Clients allow you to improve your organisaton's security posture by provisioning granular API access specific to each application's use case.

API Clients and the roles you assign to them allow you to scope API access on 3 different levels:

1. API clients are assigned roles that define the API endpoints they can interact with.
2. API clients are assigned environments - e.g. DEV, TEST, PROD - that they are allowed to make API calls to. Environments are an add-on feature and may not be available to your workspace.
3. API clients are assigned projects which scopes their API access to specific assets within those projects.

This allows you to create individual clients specific not only to API endpoints but the various projects within your workspace.

Creating a Client Role

To create an API Client, you first need to create a client role which dictates the endpoints associated clients can access. This can be done by heading over to Workspace Access => API clients => Client roles => Add client role.

Creating a new client role

• Provide a readable name for the new client role that reflects it permissions. For example, "Recipe Operator" for a role that is able to interact with Recipe API endpoints.

• Select the required endpoints for this role. All Workato API endpoints available to your workspace have been enumerated out under the various sections.

• Save your role after you are done. You can always adjust this role's privileges later on.

Creating an API Client

To create an API Client, head over to Workspace Access => API clients => API clients => Create API client.

Creating a new API client

• Provide a readable name for the new client that reflects it's purpose. For example, "Sales and Marketing - Recipe Operator" for an API client that will be used by the Sales and Marketing team to operate their recipes via the API.

• Select the appropriate client role which dictates the endpoints this API client has access to.

• If your workspace has environments enabled, select the environment which this API client has access to.

• Select the projects which this API client has access to. Choose only the projects that are related to the team that is going to use this API client. Project access rules apply to all assets that can be scoped to projects including connections, recipes, folders, lookup tables, properties, API Platform collections and API Platform API Clients

WARNING

Take note that API clients for Embedded partners with access to embedded APIs will have access to all customer workspaces and projects.

• Optionally, add allowed IP ranges that API requests using this token can originate from. This secures access to Workato's developer APIs further if you have a static server calling our APIs.

• After creating an API client, you will be shown a "view-once" API token used for authentication. It is recommended that you store this token in a secrets vault like AWS secrets manager as you will not be able to retrieve the API token again.

New view-once API token

Updating an API client or client role

Any updates made to API clients or client roles are immediately enforced.

• Adding or removing privileges to a client role will immediately impact all incoming requests from associated API clients.

• Updating an API client's role or project access will immediately impact all incoming API requests.

Refreshing API Client tokens

• In enforce regular token rotation and reduce the impacts of compromised API tokens, you may regenerate a new API token for the same client, which will invalidate the previous API token. Legacy API Client tokens cannot be regenerated.

• Compromised tokens may be due to user error when dealing with custom scripts or applications that upload tokens in plain text to public websites like Github public repositories or documentation.

Deleting an API client or client role

Deleting API clients or client roles cause all requests to be rejected.

• Deleting an API client will cause all incoming requests using its API token to start being rejected immediately.

• Deleting an API client role will cause all incoming requests from associated API clients to be start being rejected immediately.

FAQs for managing API clients and client roles

1. How should I configure client roles?

Client roles should be configured with use cases in mind. For example, a "Recipe Operator" client role might have endpoint access to start/stop recipes whereas a "Project Deployment" client role might have access to Recipe Lifecycle Management and Environment Properties endpoints. This can be used in conjunction with project scoping on the API client level to achieve access scoped to both use case and projects.

As a best practice, the Principle Of Least Privilege should be employed when defining roles such that API clients have the most narrow set of permissions needed to acheive the desired outcome.

2. How should I configure API clients?

API clients should be configured with use case and department/project in mind. For example, a "Sales and Marketing - Recipe Operator" API client can be provisioned specifically for the Sales and Marketing team. The nomenclature and distinction between departments is flexible and should be based on what makes sense for your team. Keep in mind that greater granularity in permissions increases security but comes at the expense of greater complexity as you have to juggle more API tokens.

3. Where should I store my API client tokens?

API client tokens are view-once, meaning that if they are misplaced, they are lost forever. To recover the API client, you will need to regenerate the token.

Ensure that you store these tokens upon creation in a secure location with controlled access. We recommend you consider tools like AWS secrets manager as a way to manage these tokens, especially if you are planning to generate multiple tokens for various teams.

4. Who has access to API clients and how do I control access?

All admins in your workspace have access to API clients through their privilege on "Workspace Access" in their role. Take care when adding users as admins as they have the power to create, edit and delete API clients which may impact existing automations using Workato's APIs.

When creating custom roles in your team, you can give access to API clients under the "Workspace Access" section and selecting API clients. Any user assigned this custom role will have full access to the API clients tool.

5. Why are some endpoints not compatible in my "TEST" and "PROD" environments?

Certain API endpoints in Workato are only available in the "DEV" environment such as "Project deployments" and "Workspace Collaborators". This is because you can only manage these tools from your "DEV" environment.