Product UpdatesStatus PageWorkato Academy
English
Get a trial
Developer API
Resources
Workspace details

# Workato Identity IAM

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

# Quick reference

Type Resource Description
GET /api/iam/users List users in the workspace.
GET /api/iam/users/:user-id Retrieve details for a specific user by ID.
POST /api/iam/users Create one or more new users.
PUT /api/iam/users/:user-id Update an existing user.
DELETE /api/iam/users/:user-id Delete a user from the workspace.
POST /api/iam/users/:user-id/add_to_group Add a user to a specific group.
POST /api/iam/users/:user-id/remove_from_group Remove a user from a specific group.
GET /api/iam/user_groups List user groups in the current environment.
GET /api/iam/user_groups/:user-group-id Retrieve details for a specific user group by ID.
POST /api/iam/user_groups Create a new user group.
PUT /api/iam/user_groups/:user-group-id Update an existing user group.
DELETE /api/iam/user_groups/:user-group-id Delete a user group.
POST /api/iam/user_groups/:user-group-id/add_users Add multiple users to a group.
DELETE /api/iam/user_groups/:user-group-id/remove_users Remove multiple users from a group.
GET /api/iam/user_groups/:user-group-id/members List all members of a user group.
GET /api/iam/app_links List app links in the current environment.
POST /api/iam/app_links Create an app link.
DELETE /api/iam/app_links/:id Delete an app link by ID.
DELETE /api/iam/app_links Delete app links by IDs.

# Users

The following endpoints enable you to manage Workato Identity users:

# List users

List all users in your workspace.

GET /api/iam/users

# Query parameters

Name Type Description
query string
optional		 Search query to filter users.
emails[] array[string]
optional		 Filter by email addresses.
user_ids[] array[string]
optional		 Filter by user IDs.
name string
optional		 Filter by user name.
user_group_ids[] array[string]
optional		 Filter by user group IDs.
environment_id string
optional		 Filter group membership by environment ID.
order_by string
optional		 Sort by name, email, or status.
order string
optional		 Sort direction: asc or desc.
page integer
optional		 Page number. Defaults to 1.
per_page integer
optional		 Page size. Max/default is 100.
# Sample request
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
{
  "data": [
    {
      "id": "user-id",
      "email": "[email protected]",
      "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.

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

# URL parameters

Name Type Description
user-id string
required		 User ID.
# Sample request
curl  -X GET 'https://www.workato.com/api/iam/users/:user-id' \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json'
# Response
{
  "data": {
    "id": "user-id",
    "email": "[email protected]",
    "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.

POST /api/iam/users

# Payload

Name Type Description
users[] array
required		 Array of user objects to create.
users[].email string
optional		 User email address.
users[].name string
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
curl  -X POST https://www.workato.com/api/iam/users \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d '{
            "users": [
              {
                "email": "[email protected]",
                "name": "Jade Anderson",
                "user_group_ids": ["user-group-id"],
                "environment_types": ["dev"]
              }
            ]
          }'
# Response
{
  "data": {
    "id": "new-user-id"
  }
}

# Update user

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

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

# URL parameters

Name Type Description
user-id string
required		 User ID.

# Payload

Name Type Description
name string
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
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
{
  "data": {
    "id": "user-id",
    "email": "[email protected]",
    "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.

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

# URL parameters

Name Type Description
user-id string
required		 User ID.
# Sample request
curl  -X DELETE 'https://www.workato.com/api/iam/users/:user-id' \
      -H 'Authorization: Bearer <api_token>'
# Response
{
  "data": null
}

# Add user to group

Add a user to a specific user group.

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

# URL parameters

Name Type Description
user-id string
required		 User ID.

# Payload

Name Type Description
user_group_id string
required		 User group ID.
# Sample request
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
{
  "data": {
    "id": "user-id",
    "email": "[email protected]",
    "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.

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

# URL parameters

Name Type Description
user-id string
required		 User ID.

# Payload

Name Type Description
user_group_id string
required		 User group ID.
# Sample request
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
{
  "data": {
    "id": "user-id",
    "email": "[email protected]",
    "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.

GET /api/iam/user_groups

# Query parameters

Name Type Description
query string
optional		 Search query to filter user groups.
order_by string
optional		 Field to order results by. Allowed: name.
order string
optional		 Sort direction: asc or desc.
page integer
optional		 Page number. Defaults to 1.
per_page integer
optional		 Page size. Max/default is 100.
# Sample request
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
{
  "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.

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

# URL parameters

Name Type Description
user-group-id string
required		 User group ID.
# Sample request
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
{
  "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.

POST /api/iam/user_groups

# Payload

Name Type Description
user_group.name string
required		 Name of the user group.
# Sample request
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
{
  "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.

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

# URL parameters

Name Type Description
user-group-id string
required		 User group ID.

# Payload

Name Type Description
user_group.name string
required		 Updated name for the user group.
# Sample request
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
{
  "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.

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

# URL parameters

Name Type Description
user-group-id string
required		 User group ID.
# Sample request
curl  -X DELETE 'https://www.workato.com/api/iam/user_groups/:user-group-id' \
      -H 'Authorization: Bearer <api_token>'
# Response
{
  "data": null
}

# Add users to group

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

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

# URL parameters

Name Type Description
user-group-id string
required		 User group ID.

# Payload

Name Type Description
user_ids[] array[string]
required		 Array of user IDs to add to the group.
# Sample request
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
{
  "data": null
}

# Remove users from group

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

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

# URL parameters

Name Type Description
user-group-id string
required		 User group ID.

# Payload

Name Type Description
user_ids[] array[string]
required		 Array of user IDs to remove from the group.
# Sample request
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
{
  "data": null
}

# List group members

List all members of a specific user group.

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

# URL parameters

Name Type Description
user-group-id string
required		 User group ID.

# Query parameters

Name Type Description
page integer
optional		 Page number. Defaults to 1.
per_page integer
optional		 Page size. Max/default is 100.
# Sample request
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
{
  "data": [
    {
      "id": "user-id",
      "email": "[email protected]",
      "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
  }
}

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

List all app links in the current environment.

GET /api/iam/app_links

# Query parameters

Name Type Description
app_type string
optional		 App type: slack, teams, or matrix.
app_user_id string
optional		 App user ID.
app_user_ids[] array[string]
optional		 App user IDs.
user_id string
optional		 Workato user ID.
user_ids[] array[string]
optional		 Workato user IDs.
state string
optional		 State: initial or linked.
order_by string
optional		 Sort by app_type, state, linked_at, or created_at.
order string
optional		 Sort direction: asc or desc.
page integer
optional		 Page number. Defaults to 1.
per_page integer
optional		 Page size. Set to the default maximum of 100.
# Sample request
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
{
  "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": "[email protected]",
      "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.

POST /api/iam/app_links

# Payload

Name Type Description
app_type string
required		 App type: slack, teams, or matrix.
app_user_id string
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_id string
optional		 Workato user ID. The link is created in initial state if omitted.
# Sample request
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
{
  "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.

DELETE /api/iam/app_links/:id

# URL parameters

Name Type Description
id string
required		 App link ID.
# Sample request
curl  -X DELETE 'https://www.workato.com/api/iam/app_links/:id' \
      -H 'Authorization: Bearer <api_token>'
# Response
{
  "data": null
}

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

DELETE /api/iam/app_links

# Payload

Name Type Description
ids[] array[string]
optional		 App link IDs to delete.
# Sample request
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
{
  "data": null
}
← Get workspace details
Embedded →


Last updated: 2/26/2026, 3:23:32 PM

On this page