Product UpdatesStatus PageWorkato Academy
English
日本語
Get a trial

Workato Identity IAM ​

The Workato Identity APIs allow you to programmatically manage user identities, group memberships, and access control.

Rate limits ​

Workato Identity IAM resources have the following rate limits:

Quick reference ​

TypeResourceDescription
GET/api/iam/usersList users in the workspace.
GET/api/iam/users/:user-idRetrieve details for a specific user by ID.
POST/api/iam/usersCreate one or more new users.
PUT/api/iam/users/:user-idUpdate an existing user.
DELETE/api/iam/users/:user-idDelete a user from the workspace.
POST/api/iam/users/:user-id/add_to_groupAdd a user to a specific group.
POST/api/iam/users/:user-id/remove_from_groupRemove a user from a specific group.
GET/api/iam/user_groupsList user groups in the current environment.
GET/api/iam/user_groups/:user-group-idRetrieve details for a specific user group by ID.
POST/api/iam/user_groupsCreate a new user group.
PUT/api/iam/user_groups/:user-group-idUpdate an existing user group.
DELETE/api/iam/user_groups/:user-group-idDelete a user group.
POST/api/iam/user_groups/:user-group-id/add_usersAdd multiple users to a group.
DELETE/api/iam/user_groups/:user-group-id/remove_usersRemove multiple users from a group.
GET/api/iam/user_groups/:user-group-id/membersList all members of a user group.
GET/api/iam/app_linksList app links in the current environment.
POST/api/iam/app_linksCreate an app link.
DELETE/api/iam/app_links/:idDelete an app link by ID.
DELETE/api/iam/app_linksDelete app links by IDs.

Users ​

The following endpoints enable you to manage Workato Identity users:

List users ​

List all users in your workspace.

shell
GET /api/iam/users

Query parameters ​

NameTypeDescription
querystring
optional		Search query to filter users.
emails[]array[string]
optional		Filter by email addresses.
user_ids[]array[string]
optional		Filter by user IDs.
namestring
optional		Filter by user name.
user_group_ids[]array[string]
optional		Filter by user group IDs.
environment_idstring
optional		Filter group membership by environment ID.
order_bystring
optional		Sort by name, email, or status.
orderstring
optional		Sort direction: asc or desc.
pageinteger
optional		Page number. Defaults to 1.
per_pageinteger
optional		Page size. Max/default is 100.
Sample request ​
shell
curl  -X GET 'https://www.workato.com/api/iam/users?page=1&per_page=100' \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json'
Response ​
json
{
  "data": [
    {
      "id": "user-id",
      "email": "j.anderson@example.com",
      "name": "Jade Anderson",
      "status": "active",
      "last_signed_in_at": "2025-01-15T10:30:00Z",
      "created_at": "2025-01-01T00:00:00Z",
      "environment_ids": ["env-id"],
      "user_groups": [
        {
          "id": "user-group-id",
          "environment_id": "env-id",
          "name": "Developers"
        }
      ]
    }
  ],
  "total": 1,
  "page": {
    "number": 1,
    "size": 100
  }
}

Get user by ID ​

Retrieve details for a specific user by ID.

shell
GET /api/iam/users/:user-id

URL parameters ​

NameTypeDescription
user-idstring
required		User ID.
Sample request ​
shell
curl  -X GET 'https://www.workato.com/api/iam/users/:user-id' \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json'
Response ​
json
{
  "data": {
    "id": "user-id",
    "email": "j.anderson@example.com",
    "name": "Jade Anderson",
    "status": "active",
    "last_signed_in_at": "2025-01-15T10:30:00Z",
    "created_at": "2025-01-01T00:00:00Z",
    "environment_ids": ["env-id"],
    "user_groups": [
      {
        "id": "user-group-id",
        "environment_id": "env-id",
        "name": "Developers"
      }
    ]
  }
}

Create user ​

Create one or more new users in your workspace.

shell
POST /api/iam/users

Payload ​

NameTypeDescription
users[]array
required		Array of user objects to create.
users[].emailstring
optional		User email address.
users[].namestring
optional		User display name.
users[].user_group_ids[]array[string]
optional		Group IDs. You must provide environment_types[] if you provide Group IDs.
users[].environment_types[]array[string]
optional		Environment types. For example: dev, test, or prod.
Sample request ​
shell
curl  -X POST https://www.workato.com/api/iam/users \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d '{
            "users": [
              {
                "email": "j.anderson@acme.com",
                "name": "Jade Anderson",
                "user_group_ids": ["user-group-id"],
                "environment_types": ["dev"]
              }
            ]
          }'
Response ​
json
{
  "data": {
    "id": "new-user-id"
  }
}

Update user ​

Update an existing user's information, including name and group memberships.

shell
PUT /api/iam/users/:user-id

URL parameters ​

NameTypeDescription
user-idstring
required		User ID.

Payload ​

NameTypeDescription
namestring
optional		Updated user name.
user_group_ids[]array[string]
optional		Updated list of group IDs.
environment_types[]array[string]
optional		Environment types (dev, test, prod).
environment_user_groups[]array[object]
optional		Explicit environment group assignments with id and environment_id.
Sample request ​
shell
curl  -X PUT https://www.workato.com/api/iam/users/:user-id \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d '{
            "name": "Developer CI/CD",
            "environment_types": ["dev", "test"],
            "environment_user_groups": [
              {"id": "user-group-id", "environment_id": "env-id"}
            ]
          }'
Response ​
json
{
  "data": {
    "id": "user-id",
    "email": "j.anderson@example.com",
    "name": "Developer CI/CD",
    "status": "active",
    "last_signed_in_at": "2025-01-15T10:30:00Z",
    "created_at": "2025-01-01T00:00:00Z",
    "environment_ids": ["env-id", "env-id-2"],
    "user_groups": [
      {
        "id": "user-group-id",
        "environment_id": "env-id",
        "name": "Developers"
      }
    ]
  }
}

Delete user ​

Delete a user from your workspace.

PERMANENT ACTION

This action permanently removes the user from your workspace. This action doesn't delete the user from the system.

shell
DELETE /api/iam/users/:user-id

URL parameters ​

NameTypeDescription
user-idstring
required		User ID.
Sample request ​
shell
curl  -X DELETE 'https://www.workato.com/api/iam/users/:user-id' \
      -H 'Authorization: Bearer <api_token>'
Response ​
json
{
  "data": null
}

Add user to group ​

Add a user to a specific user group.

shell
POST /api/iam/users/:user-id/add_to_group

URL parameters ​

NameTypeDescription
user-idstring
required		User ID.

Payload ​

NameTypeDescription
user_group_idstring
required		User group ID.
Sample request ​
shell
curl  -X POST https://www.workato.com/api/iam/users/:user-id/add_to_group \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d '{
            "user_group_id": "user_group_id"
          }'
Response ​
json
{
  "data": {
    "id": "user-id",
    "email": "j.anderson@acme.com",
    "name": "Jade Anderson",
    "status": "active",
    "last_signed_in_at": "2025-01-15T10:30:00Z",
    "created_at": "2025-01-01T00:00:00Z",
    "environment_ids": ["env-id"],
    "user_groups": [
      {
        "id": "user-group-id",
        "environment_id": "env-id",
        "name": "Developers"
      }
    ]
  }
}

Remove user from group ​

Remove a user from a specific user group.

shell
POST /api/iam/users/:user-id/remove_from_group

URL parameters ​

NameTypeDescription
user-idstring
required		User ID.

Payload ​

NameTypeDescription
user_group_idstring
required		User group ID.
Sample request ​
shell
curl  -X POST https://www.workato.com/api/iam/users/:user-id/remove_from_group \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d '{
            "user_group_id": "user_group_id"
          }'
Response ​
json
{
  "data": {
    "id": "user-id",
    "email": "j.anderson@acme.com",
    "name": "Jade Anderson",
    "status": "active",
    "last_signed_in_at": "2025-01-15T10:30:00Z",
    "created_at": "2025-01-01T00:00:00Z",
    "environment_ids": ["env-id"],
    "user_groups": []
  }
}

User Groups ​

The following endpoints enable you to manage Workato Identity groups:

List user groups ​

List all user groups in the current environment.

shell
GET /api/iam/user_groups

Query parameters ​

NameTypeDescription
querystring
optional		Search query to filter user groups.
order_bystring
optional		Field to order results by. Allowed: name.
orderstring
optional		Sort direction: asc or desc.
pageinteger
optional		Page number. Defaults to 1.
per_pageinteger
optional		Page size. Max/default is 100.
Sample request ​
shell
curl  -X GET 'https://www.workato.com/api/iam/user_groups?page=1&per_page=100' \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json'
Response ​
json
{
  "data": [
    {
      "id": "user-group-id",
      "environment_id": "env-id",
      "name": "Developers",
      "users_count": 10,
      "created_at": "2025-01-01T00:00:00Z",
      "updated_at": "2025-01-10T00:00:00Z"
    }
  ],
  "total": 1,
  "page": {
    "number": 1,
    "size": 100
  }
}

Get user group by ID ​

Retrieve details of a specific user group by ID.

shell
GET /api/iam/user_groups/:user-group-id

URL parameters ​

NameTypeDescription
user-group-idstring
required		User group ID.
Sample request ​
shell
curl  -X GET 'https://www.workato.com/api/iam/user_groups/:user-group-id' \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json'
Response ​
json
{
  "data": {
    "id": "user-group-id",
    "environment_id": "env-id",
    "name": "Developers",
    "users_count": 10,
    "created_at": "2025-01-01T00:00:00Z",
    "updated_at": "2025-01-10T00:00:00Z"
  }
}

Create user group ​

Create a new user group in your workspace.

shell
POST /api/iam/user_groups

Payload ​

NameTypeDescription
user_group.namestring
required		Name of the user group.
Sample request ​
shell
curl  -X POST https://www.workato.com/api/iam/user_groups \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d '{
            "user_group": {
              "name": "Sales Group"
            }
          }'
Response ​
json
{
  "data": {
    "id": "user-group-id",
    "environment_id": "env-id",
    "name": "Sales Group",
    "users_count": 0,
    "created_at": "2025-01-20T00:00:00Z",
    "updated_at": "2025-01-20T00:00:00Z"
  }
}

Update user group ​

Update an existing user group name.

shell
PUT /api/iam/user_groups/:user-group-id

URL parameters ​

NameTypeDescription
user-group-idstring
required		User group ID.

Payload ​

NameTypeDescription
user_group.namestring
required		Updated name for the user group.
Sample request ​
shell
curl  -X PUT https://www.workato.com/api/iam/user_groups/:user-group-id \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d '{
            "user_group": {
              "name": "Sales training group"
            }
          }'
Response ​
json
{
  "data": {
    "id": "user-group-id",
    "environment_id": "env-id",
    "name": "Sales training group",
    "users_count": 10,
    "created_at": "2025-01-01T00:00:00Z",
    "updated_at": "2025-01-20T00:00:00Z"
  }
}

Delete user group ​

Delete a user group from your workspace.

GROUP DELETION DOESN'T DELETE USERS

This action permanently removes the user group. Users assigned to the group aren't deleted, but are removed from this group.

shell
DELETE /api/iam/user_groups/:user-group-id

URL parameters ​

NameTypeDescription
user-group-idstring
required		User group ID.
Sample request ​
shell
curl  -X DELETE 'https://www.workato.com/api/iam/user_groups/:user-group-id' \
      -H 'Authorization: Bearer <api_token>'
Response ​
json
{
  "data": null
}

Add users to group ​

Add multiple users to a user group in a single operation.

shell
POST /api/iam/user_groups/:user-group-id/add_users

URL parameters ​

NameTypeDescription
user-group-idstring
required		User group ID.

Payload ​

NameTypeDescription
user_ids[]array[string]
required		Array of user IDs to add to the group.
Sample request ​
shell
curl  -X POST https://www.workato.com/api/iam/user_groups/:user-group-id/add_users \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d '{
            "user_ids": ["user-id-1", "user-id-2"]
          }'
Response ​
json
{
  "data": null
}

Remove users from group ​

Remove multiple users from a user group in a single operation.

shell
DELETE /api/iam/user_groups/:user-group-id/remove_users

URL parameters ​

NameTypeDescription
user-group-idstring
required		User group ID.

Payload ​

NameTypeDescription
user_ids[]array[string]
required		Array of user IDs to remove from the group.
Sample request ​
shell
curl  -X DELETE https://www.workato.com/api/iam/user_groups/:user-group-id/remove_users \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d '{
            "user_ids": ["user-id-1", "user-id-2"]
          }'
Response ​
json
{
  "data": null
}

List group members ​

List all members of a specific user group.

shell
GET /api/iam/user_groups/:user-group-id/members

URL parameters ​

NameTypeDescription
user-group-idstring
required		User group ID.

Query parameters ​

NameTypeDescription
pageinteger
optional		Page number. Defaults to 1.
per_pageinteger
optional		Page size. Max/default is 100.
Sample request ​
shell
curl  -X GET 'https://www.workato.com/api/iam/user_groups/:user-group-id/members?page=1&per_page=100' \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json'
Response ​
json
{
  "data": [
    {
      "id": "user-id",
      "email": "j.anderson@acme.com",
      "name": "Jade Anderson",
      "status": "active",
      "last_signed_in_at": "2025-01-15T10:30:00Z",
      "created_at": "2025-01-01T00:00:00Z",
      "environment_ids": ["env-id"],
      "user_groups": [
        {
          "id": "user-group-id",
          "environment_id": "env-id",
          "name": "Developers"
        }
      ]
    }
  ],
  "total": 1,
  "page": {
    "number": 1,
    "size": 100
  }
}

An app link maps a user's Workato Identity account to their corresponding account in a specific app, such as Slack, Microsoft Teams, or Workato GO. For example, it connects jade@acme.com in Workato Identity to @jade in Slack. You can create app links in Workato Identity without requiring users to sign in first. This allows you to send app events, notifications, or automations to your entire organization through a connected app immediately.

The following endpoints enable you to manage Workato Identity app links:

List all app links in the current environment.

shell
GET /api/iam/app_links

Query parameters ​

NameTypeDescription
app_typestring
optional		App type: slack, teams, or matrix.
app_user_idstring
optional		App user ID.
app_user_ids[]array[string]
optional		App user IDs.
user_idstring
optional		Workato user ID.
user_ids[]array[string]
optional		Workato user IDs.
statestring
optional		State: initial or linked.
order_bystring
optional		Sort by app_type, state, linked_at, or created_at.
orderstring
optional		Sort direction: asc or desc.
pageinteger
optional		Page number. Defaults to 1.
per_pageinteger
optional		Page size. Set to the default maximum of 100.
Sample request ​
shell
curl  -X GET 'https://www.workato.com/api/iam/app_links?page=1&per_page=100' \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json'
Response ​
json
{
  "data": [
    {
      "id": "7H9UjixTng97i7dTSXMYpo",
      "app_type": "slack",
      "app_user_id": "/slack/teams/T083UTJ97C1/users/U083G78PZV0",
      "user_id": "user-id",
      "state": "linked",
      "linked_at": "2025-01-15T10:30:00Z",
      "created_at": "2025-01-01T00:00:00Z",
      "updated_at": "2025-01-10T00:00:00Z",
      "auth_link": null
    },
    {
      "id": "4YYoEcATHdUVHceXUHymKY",
      "app_type": "teams",
      "app_user_id": "/teams/teams/1a30ead4-ab61-473e-8c8a-a83eb2948145/users/cb3bbf8f-579e-41c6-89ad-5927346f8944",
      "user_id": "user-id",
      "state": "linked",
      "linked_at": "2025-01-15T10:30:00Z",
      "created_at": "2025-01-01T00:00:00Z",
      "updated_at": "2025-01-10T00:00:00Z",
      "auth_link": null
    },
    {
      "id": "yDQe8Ua4PKQWT7hDMAPgi",
      "app_type": "matrix",
      "app_user_id": "marco@acme.com",
      "user_id": "user-id",
      "state": "linked",
      "linked_at": "2025-01-15T10:30:00Z",
      "created_at": "2025-01-01T00:00:00Z",
      "updated_at": "2025-01-10T00:00:00Z",
      "auth_link": null
    }
  ],
  "total": 3,
  "page": {
    "number": 1,
    "size": 100
  }
}

Create a new app link in your workspace.

shell
POST /api/iam/app_links

Payload ​

NameTypeDescription
app_typestring
required		App type: slack, teams, or matrix.
app_user_idstring
required		User ID in the app. Format varies by app type:
• Slack: /slack/teams/{team_id}/users/{user_id}
• Teams: /teams/teams/{team_uuid}/users/{user_uuid}
• Matrix (GO): User email address
user_idstring
optional		Workato user ID. The link is created in initial state if omitted.
Sample request ​
shell
curl  -X POST https://www.workato.com/api/iam/app_links \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d '{
            "app_type": "slack",
            "app_user_id": "/slack/teams/T083UTJ97C1/users/U083G78PZV0",
            "user_id": "user-id"
          }'
Response ​
json
{
  "data": {
    "id": "app-link-id",
    "app_type": "slack",
    "app_user_id": "/slack/teams/T083UTJ97C1/users/U083G78PZV0",
    "user_id": "user-id",
    "state": "linked",
    "linked_at": "2025-01-15T10:30:00Z",
    "created_at": "2025-01-01T00:00:00Z",
    "updated_at": "2025-01-10T00:00:00Z",
    "auth_link": "http://id.workato.com/portal/workspaces/<ID>/environments/<ENV ID>/sign-in?app_link_unique_id=<APP LINK ID>"
  }
}

Delete an app link from your workspace.

shell
DELETE /api/iam/app_links/:id

URL parameters ​

NameTypeDescription
idstring
required		App link ID.
Sample request ​
shell
curl  -X DELETE 'https://www.workato.com/api/iam/app_links/:id' \
      -H 'Authorization: Bearer <api_token>'
Response ​
json
{
  "data": null
}

Delete multiple app links from your workspace in a single operation.

shell
DELETE /api/iam/app_links

Payload ​

NameTypeDescription
ids[]array[string]
optional		App link IDs to delete.
Sample request ​
shell
curl  -X DELETE 'https://www.workato.com/api/iam/app_links' \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d '{
            "ids": ["app-link-id-1", "app-link-id-2"]
          }'
Response ​
json
{
  "data": null
}

Last updated: