Skip to main content
The Workato Developer API is included in specific pricing plans, so check your plan and contract. To create an API client, sign in with the root email address of the workspace, or as an Environment admin, a legacy Admin, or a collaborator whose custom role has the Client & access profiles privilege.

​
Find your data center

The Data center identifies the region where your Workato workspace runs. A token works only against the data center that holds the workspace.

  • Sign in to Workato and read the address in the address bar.
  • app.workato.com: choose US
  • app.eu.workato.com: choose EU
  • app.jp.workato.com: choose JP
  • app.sg.workato.com: choose SG
  • app.au.workato.com: choose AU
  • app.il.workato.com: choose IL
  • app.uk.workato.com: choose UK
  • app.kr.workato.com: choose KR
  • app.workatoapp.cn: choose CN
  • app.trial.workato.com: choose Self-service, used by Workato Free, Workato Pro and Developer Sandbox workspaces
  • Virtual Private Workato workspaces use their own address and have no option here.
  • Select the matching option in the Data center field in StackOne Hub.

​
Create a client role

The client role lists the API endpoints the token may call. Read endpoints cover every read; the two write endpoints in the last item are optional.

1

Sign in to Workato

Sign in to your Workato account at the address of your data center, for example
Workato US or
Workato EU, as a user who can create API clients.

  • Navigate to Workspace admin > API clients > Client roles.
  • Select Add client role.
2

Name the role and choose the endpoints

Enter a name such as StackOne Integration, then tick the endpoints below under their sections.

  • Tick Get collaborators GET /api/members to list collaborators. The connection test uses it too.
  • Tick GET /api/members/:id to read a single collaborator.
  • Under Admin > Workspace details > Workspace details, tick Get details GET /api/users/me to read the workspace details of the token.
  • Tick GET /api/user_groups and GET /api/user_groups/:id to read collaborator groups, and GET /api/user_groups/:id/members to read their members.
  • Tick GET /api/members/:id/project_grants and GET /api/user_groups/:id/project_grants to read the project roles each collaborator has directly and through groups.
  • Tick GET /api/environment_roles, GET /api/project_roles and GET /api/roles (legacy roles) to list roles, and GET /api/project_roles/:id to read one project role.
  • Tick GET /api/members/:id/privileges, GET /api/members/:id/projects_privileges, GET /api/environment_roles/:id and GET /api/developer_api_clients only if you use the matching read-only actions in StackOne. Reading collaborators, groups and roles does not need them.
  • Tick DELETE /api/members/:id and POST /api/user_groups/:id/members only if you want StackOne to remove a collaborator or add members to a group. Without them every read still works and these two actions are refused.
3

Save the role

Select Save.

  • Workato applies changes to a client role to its API clients straight away.

​
Create the API client

The API client holds the token that StackOne sends with every request.

1

Create the client

Navigate to Workspace admin > API clients and select Create API client.

  • Enter a name such as StackOne Integration.
  • Select the client role you just created.
2

Choose the environment and projects

If your workspace uses environments, select DEV, because Workato offers the collaborator endpoints only to clients with DEV access. Project roles in TEST and PROD projects appear only if Workato lets a DEV client read them.

  • Allow all projects, so StackOne reads project roles in every project. Workato limits a client to the projects you select.
  • Leave the allowed IP ranges empty, or add StackOne’s IP addresses so the token works only from StackOne. Workato refuses requests from any address outside the ranges, so update them when StackOne changes its list.
3

Copy the token

Copy the API token Workato shows after it creates the client, store it securely for use later, then select Save.

  • The token is shown once and cannot be retrieved later. If you lose it, regenerate it.
  • Paste it into the API Token field in StackOne Hub.

​
Rotate or revoke the token

Workato lists no expiry date for an API client token. It stops working when you regenerate it or delete the client.

  • Navigate to Workspace admin > API clients and open the API client.
  • Select the refresh icon in the top right corner, then Regenerate token. The previous token fails straight away, so paste the new token into StackOne Hub.
  • Workato also revokes a token it finds in a public GitHub repository and emails the workspace admins. Regenerate the token and paste it into StackOne Hub.
  • Delete the API client or its client role to make Workato reject every request that uses the token.

​
Linking the Account from the Hub

1

Navigate to the Hub

Use one of the three Linking Account Methods to access the Hub.
2

Fill out the fields

Fill out the following fields using details from your provider:
  • Data center
  • API Token
3

Connect

  • Click Connect
  • If applicable, the provider will redirect you to a sign-in or authorization page. Complete the provider’s authorization flow.
  • Once authorization is successful, you will see a confirmation popup

If the account linking is successful, you will see the newly linked account on your Accounts page.