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.

Watch a quick video guide: Onboard genie users with Workato Identity IAM

Rate limits ​

Workato Identity IAM resources have the following rate limits:

TypeResourceQuota
AllAll Workato Identity IAM endpoints60 requests per minute

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.

GET https://YOUR_DATA_CENTER/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://YOUR_DATA_CENTER/api/iam/users?page=:page_value&per_page=:per_page_value' \
      -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.

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

URL parameters ​

NameTypeDescription
user-idstring
required		User ID.
Sample request ​
shell
curl  -X GET 'https://YOUR_DATA_CENTER/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.

POST https://YOUR_DATA_CENTER/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.
users[].send_invitationboolean
optional		Whether to send an email invitation to the user. Defaults to true. Must be false or omitted when state is active.
users[].statestring
optional		Initial state of the user. Either active or invited. Defaults to invited.
Sample request ​
shell
curl  -X POST https://YOUR_DATA_CENTER/api/iam/users \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d '{
            "users": [
              {
                "email": ":email",
                "name": ":name",
                "user_group_ids": [":user_group_id"],
                "environment_types": [":environment_type"]
              }
            ]
          }'
Response ​
json
{
  "data": [
    {
      "id": "l1fEi5N0ts0aMbLe91",
      "invitation_url": "https://www.workato.com/invitations/example-token"
    }
  ]
}

Update user ​

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

PUT https://YOUR_DATA_CENTER/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://YOUR_DATA_CENTER/api/iam/users/:user-id \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d '{
            "name": ":name",
            "environment_types": [":environment_type_1", ":environment_type_2"],
            "environment_user_groups": [
              {"id": ":user_group_id", "environment_id": ":environment_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.

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

URL parameters ​

NameTypeDescription
user-idstring
required		User ID.
Sample request ​
shell
curl  -X DELETE 'https://YOUR_DATA_CENTER/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.

POST https://YOUR_DATA_CENTER/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.
environment_idstring
optional		Environment ID. Defaults to the Development environment.
Sample request ​
shell
curl  -X POST https://YOUR_DATA_CENTER/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.

POST https://YOUR_DATA_CENTER/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.
environment_idstring
optional		Environment ID. Defaults to the Development environment.
Sample request ​
shell
curl  -X POST https://YOUR_DATA_CENTER/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.

GET https://YOUR_DATA_CENTER/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://YOUR_DATA_CENTER/api/iam/user_groups?page=:page_value&per_page=:per_page_value' \
      -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.

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

URL parameters ​

NameTypeDescription
user-group-idstring
required		User group ID.
Sample request ​
shell
curl  -X GET 'https://YOUR_DATA_CENTER/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.

POST https://YOUR_DATA_CENTER/api/iam/user_groups

Payload ​

NameTypeDescription
user_group.namestring
required		Name of the user group.
Sample request ​
shell
curl  -X POST https://YOUR_DATA_CENTER/api/iam/user_groups \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d '{
            "user_group": {
              "name": ":name"
            }
          }'
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.

PUT https://YOUR_DATA_CENTER/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://YOUR_DATA_CENTER/api/iam/user_groups/:user-group-id \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d '{
            "user_group": {
              "name": ":name"
            }
          }'
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.

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

URL parameters ​

NameTypeDescription
user-group-idstring
required		User group ID.
Sample request ​
shell
curl  -X DELETE 'https://YOUR_DATA_CENTER/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.

POST https://YOUR_DATA_CENTER/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://YOUR_DATA_CENTER/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.

DELETE https://YOUR_DATA_CENTER/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://YOUR_DATA_CENTER/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.

GET https://YOUR_DATA_CENTER/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://YOUR_DATA_CENTER/api/iam/user_groups/:user-group-id/members?page=:page_value&per_page=:per_page_value' \
      -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.

GET https://YOUR_DATA_CENTER/api/iam/app_links
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.
shell
curl  -X GET 'https://YOUR_DATA_CENTER/api/iam/app_links?page=:page_value&per_page=:per_page_value' \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json'
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.

POST https://YOUR_DATA_CENTER/api/iam/app_links
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.
shell
curl  -X POST https://YOUR_DATA_CENTER/api/iam/app_links \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d '{
            "app_type": ":app_type",
            "app_user_id": ":app_user_id",
            "user_id": ":user_id"
          }'
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.

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

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

DELETE https://YOUR_DATA_CENTER/api/iam/app_links
NameTypeDescription
ids[]array[string]
optional		App link IDs to delete.
shell
curl  -X DELETE 'https://YOUR_DATA_CENTER/api/iam/app_links' \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d '{
            "ids": [":app_link_id_1", ":app_link_id_2"]
          }'
json
{
  "data": null
}

Last updated: