Embedded API - Workato Identity IAM
The Workato Identity embedded APIs allow you to programmatically manage user identities, group memberships, and access control in a customer workspace.
Rate limits
Workato Identity IAM resources have the following rate limits:
| Type | Resource | Quota |
|---|---|---|
| All | All Workato Identity IAM embedded endpoints | 60 requests per minute |
Quick reference
Users
The following endpoints enable you to manage Workato Identity users in a customer workspace:
List users
List all users in a customer workspace.
GET https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/iam/usersURL parameters
| Name | Type | Description |
|---|---|---|
| managed_user_id | string required | Customer account ID or external ID. External IDs must be URL encoded and prefixed with an E, for example: EA2300. Append _dev, _test, or _prod to specify an environment. |
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://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/iam/users?emails[]=:email&page=:page_value&per_page=:per_page_value' \
-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 https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/iam/users/:user-idURL parameters
| Name | Type | Description |
|---|---|---|
| managed_user_id | string required | Customer account ID or external ID. External IDs must be URL encoded and prefixed with an E, for example: EA2300. Append _dev, _test, or _prod to specify an environment. |
| user-id | string required | User ID. |
Sample request
curl -X GET 'https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/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 a customer workspace.
POST https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/iam/usersURL parameters
| Name | Type | Description |
|---|---|---|
| managed_user_id | string required | Customer account ID or external ID. External IDs must be URL encoded and prefixed with an E, for example: EA2300. Append _dev, _test, or _prod to specify an environment. |
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. |
| users[].send_invitation | boolean optional | Whether to send an email invitation to the user. Defaults to true. Must be false or omitted when state is active. |
| users[].state | string optional | Initial state of the user. Either active or invited. Defaults to invited. |
Sample request
curl -X POST https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/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
{
"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/managed_users/:managed_user_id/iam/users/:user-idURL parameters
| Name | Type | Description |
|---|---|---|
| managed_user_id | string required | Customer account ID or external ID. External IDs must be URL encoded and prefixed with an E, for example: EA2300. Append _dev, _test, or _prod to specify an environment. |
| 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 type: dev, test, or prod. |
| environment_user_groups[] | array[object] optional | Explicit environment group assignments with id and environment_id. |
Sample request
curl -X PUT https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/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
{
"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 a customer workspace.
PERMANENT ACTION
This action permanently removes the user from the customer workspace. This action doesn't delete the user from the system.
DELETE https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/iam/users/:user-idURL parameters
| Name | Type | Description |
|---|---|---|
| managed_user_id | string required | Customer account ID or external ID. External IDs must be URL encoded and prefixed with an E, for example: EA2300. Append _dev, _test, or _prod to specify an environment. |
| user-id | string required | User ID. |
Sample request
curl -X DELETE 'https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/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 https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/iam/users/:user-id/add_to_groupURL parameters
| Name | Type | Description |
|---|---|---|
| managed_user_id | string required | Customer account ID or external ID. External IDs must be URL encoded and prefixed with an E, for example: EA2300. Append _dev, _test, or _prod to specify an environment. |
| user-id | string required | User ID. |
Payload
| Name | Type | Description |
|---|---|---|
| user_group_id | string required | User group ID. |
| environment_id | string optional | Environment ID. Defaults to the Development environment. |
Sample request
curl -X POST https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/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 https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/iam/users/:user-id/remove_from_groupURL parameters
| Name | Type | Description |
|---|---|---|
| managed_user_id | string required | Customer account ID or external ID. External IDs must be URL encoded and prefixed with an E, for example: EA2300. Append _dev, _test, or _prod to specify an environment. |
| user-id | string required | User ID. |
Payload
| Name | Type | Description |
|---|---|---|
| user_group_id | string required | User group ID. |
| environment_id | string optional | Environment ID. Defaults to the Development environment. |
Sample request
curl -X POST https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/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 in a customer workspace:
List user groups
List all user groups in a customer workspace.
GET https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/iam/user_groupsURL parameters
| Name | Type | Description |
|---|---|---|
| managed_user_id | string required | Customer account ID or external ID. External IDs must be URL encoded and prefixed with an E, for example: EA2300. Append _dev, _test, or _prod to specify an environment. |
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://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/iam/user_groups?page=:page_value&per_page=:per_page_value' \
-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 https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/iam/user_groups/:user-group-idURL parameters
| Name | Type | Description |
|---|---|---|
| managed_user_id | string required | Customer account ID or external ID. External IDs must be URL encoded and prefixed with an E, for example: EA2300. Append _dev, _test, or _prod to specify an environment. |
| user-group-id | string required | User group ID. |
Sample request
curl -X GET 'https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/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 a customer workspace.
POST https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/iam/user_groupsURL parameters
| Name | Type | Description |
|---|---|---|
| managed_user_id | string required | Customer account ID or external ID. External IDs must be URL encoded and prefixed with an E, for example: EA2300. Append _dev, _test, or _prod to specify an environment. |
Payload
| Name | Type | Description |
|---|---|---|
| user_group.name | string required | Name of the user group. |
Sample request
curl -X POST https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/iam/user_groups \
-H 'Authorization: Bearer <api_token>' \
-H 'Content-Type: application/json' \
-d '{
"user_group": {
"name": ":name"
}
}'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 https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/iam/user_groups/:user-group-idURL parameters
| Name | Type | Description |
|---|---|---|
| managed_user_id | string required | Customer account ID or external ID. External IDs must be URL encoded and prefixed with an E, for example: EA2300. Append _dev, _test, or _prod to specify an environment. |
| 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://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/iam/user_groups/:user-group-id \
-H 'Authorization: Bearer <api_token>' \
-H 'Content-Type: application/json' \
-d '{
"user_group": {
"name": ":name"
}
}'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 a customer 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/managed_users/:managed_user_id/iam/user_groups/:user-group-idURL parameters
| Name | Type | Description |
|---|---|---|
| managed_user_id | string required | Customer account ID or external ID. External IDs must be URL encoded and prefixed with an E, for example: EA2300. Append _dev, _test, or _prod to specify an environment. |
| user-group-id | string required | User group ID. |
Sample request
curl -X DELETE 'https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/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 https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/iam/user_groups/:user-group-id/add_usersURL parameters
| Name | Type | Description |
|---|---|---|
| managed_user_id | string required | Customer account ID or external ID. External IDs must be URL encoded and prefixed with an E, for example: EA2300. Append _dev, _test, or _prod to specify an environment. |
| 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://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/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 https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/iam/user_groups/:user-group-id/remove_usersURL parameters
| Name | Type | Description |
|---|---|---|
| managed_user_id | string required | Customer account ID or external ID. External IDs must be URL encoded and prefixed with an E, for example: EA2300. Append _dev, _test, or _prod to specify an environment. |
| 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://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/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 https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/iam/user_groups/:user-group-id/membersURL parameters
| Name | Type | Description |
|---|---|---|
| managed_user_id | string required | Customer account ID or external ID. External IDs must be URL encoded and prefixed with an E, for example: EA2300. Append _dev, _test, or _prod to specify an environment. |
| 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://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/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
{
"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
}
}App links
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 [email protected] 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 customer's entire organization through a connected app immediately.
The following endpoints enable you to manage Workato Identity app links in a customer workspace:
List app links
List all app links in a customer workspace.
GET https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/iam/app_linksURL parameters
| Name | Type | Description |
|---|---|---|
| managed_user_id | string required | Customer account ID or external ID. External IDs must be URL encoded and prefixed with an E, for example: EA2300. Append _dev, _test, or _prod to specify an environment. |
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://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/iam/app_links?page=:page_value&per_page=:per_page_value' \
-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 app link
Create a new app link in a customer workspace.
POST https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/iam/app_linksURL parameters
| Name | Type | Description |
|---|---|---|
| managed_user_id | string required | Customer account ID or external ID. External IDs must be URL encoded and prefixed with an E, for example: EA2300. Append _dev, _test, or _prod to specify an environment. |
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://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/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"
}'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 app link
Delete an app link from a customer workspace.
DELETE https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/iam/app_links/:idURL parameters
| Name | Type | Description |
|---|---|---|
| managed_user_id | string required | Customer account ID or external ID. External IDs must be URL encoded and prefixed with an E, for example: EA2300. Append _dev, _test, or _prod to specify an environment. |
| id | string required | App link ID. |
Sample request
curl -X DELETE 'https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/iam/app_links/:id' \
-H 'Authorization: Bearer <api_token>'Response
{
"data": null
}Delete app links
Delete multiple app links from a customer workspace in a single operation.
DELETE https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/iam/app_linksURL parameters
| Name | Type | Description |
|---|---|---|
| managed_user_id | string required | Customer account ID or external ID. External IDs must be URL encoded and prefixed with an E, for example: EA2300. Append _dev, _test, or _prod to specify an environment. |
Payload
| Name | Type | Description |
|---|---|---|
| ids[] | array[string] optional | App link IDs to delete. |
Sample request
curl -X DELETE 'https://YOUR_DATA_CENTER/api/managed_users/:managed_user_id/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
}Last updated: