Roles

# Project grants

Use the following endpoints to manage a collaborator or group's project grants in an Embedded customer workspace.

API CLIENT ACCESS

Project grant endpoints can only assign project roles to environments and projects that the API client can access. For example, an API client assigned to the TEST environment can only manage TEST projects. Additionally, if an API client is assigned to specific projects, it can only manage those projects. Refer to Create a client role to configure an API client's access.

# Rate limits

The project grants resource has the following rate limit:

Type	Resource	Limit
All	All Project grants endpoints	60 requests per minute

# What are project grants?

A project grant assigns a project role to a collaborator or group. Refer to Manage project access and roles to manage assigned project roles in the UI.

# Quick reference

Type	Resource	Description
GET	/api/managed_users/:managed_user_id/project_grants/:id	Get a customer workspace project grant.
PUT	/api/managed_users/:managed_user_id/project_grants/:id	Update a customer workspace project grant.
DELETE	/api/managed_users/:managed_user_id/project_grants/:id	Delete a customer workspace project grant.
GET	/api/managed_users/:managed_user_id/:id/project_grants	List customer workspace project grants.
PUT	/api/managed_users/:managed_user_id/projects/ :id/project_grants	Add or update customer workspace project grants.

# Get a customer workspace project grant

Retrieves a project grant from an Embedded customer workspace.

GET /api/managed_users/:managed_user_id/project_grants/:id

# Path parameters

Name	Type	Description
managed_user_id	string required	The Embedded customer ID or external ID. External IDs must be URL encoded and prefixed with an `E`, for example: `EA2300`.
id	string required	The ID of the project grant to retrieve.

# Sample request

curl -X GET 'https://www.workato.com/api/managed_users/19029/project_grants/pg-AQAEnmKC-Dtt9aD' \
  -H 'Authorization: Bearer <api_token>'

# Response

{
  "data" : {
    "id": "pg-AQAEnmKC-Dtt9aD", 
    "project": {
      "id": 178229, 
      "name": "Development",
      "environment": {
        "id": 148425, 
        "type": "dev"
      }
    }, 
    "project_role": {
      "id": "pr-AQBGCnMB-JoFtKL", 
      "name": "Developers"
    },
    "user_group": null,
    "user": {
      "id": 1,
      "name" : "Taylor",
      "email": "[email protected]"
    }
  }
}

# Update a customer workspace project grant

Updates an existing project grant in an Embedded customer workspace.

PUT /api/managed_users/:managed_user_id/project_grants/:id

# Path parameters

Name	Type	Description
managed_user_id	string required	The Embedded customer ID or external ID. External IDs must be URL encoded and prefixed with an `E`, for example: `EA2300`.
id	string required	The ID of the project grant to update.

# Request body

Name	Type	Description
project_grant	object required	Defines the updated project grant.
project_grant[project_role_id]	string required	The ID of the project role to assign.

# Sample request

curl -X PUT 'https://www.workato.com/api/managed_users/19029/project_grants/pg-AQAEnmKC-Dtt9aD' \
  -H 'Authorization: Bearer <api_token>' \
  -H 'Content-Type: application/json' \
  -d '{
        "project_grant": {
          "project_role_id": "pr-AQBGCnMB-JoFtKL"
        }
      }'

# Response

{
  "data" : {
    "id": "pg-AQAEnmKC-Dtt9aD", 
    "project": {
      "id": 178229, 
      "name": "Development",
      "environment": {
        "id": 148425, 
        "type": "dev"
      } 
    }, 
    "project_role": {
      "id": "pr-AQBGCnMB-JoFtKL", 
      "name": "Developers"
    },
    "user_group": {
      "id": "am-WxEKCibh-dTXBtz",
      "name" : "Developers",
      "system": false
    },
    "user": null
  }
}

400 BAD REQUEST

A 400 Bad Request error indicates that the server couldn't process the request due to client-side issues. Common causes include malformed requests, invalid fields, or violations of field constraints, such as unsupported data types.

In the following example, the request fails because the role assignment already exists:

{ 
  "errors": [
    {
      "code": "bad_request",
      "title": "Assignment has already been taken"
    }
  ] 
}

# Delete a customer workspace project grant

Deletes a project grant from an Embedded customer workspace.

DELETE /api/managed_users/:managed_user_id/project_grants/:id

# Path parameters

Name	Type	Description
managed_user_id	string required	The Embedded customer ID or external ID. External IDs must be URL encoded and prefixed with an `E`, for example: `EA2300`.
id	string required	The ID of the project grant to delete.

# Sample request

curl -X DELETE 'https://www.workato.com/api/managed_users/19029/project_grants/pg-AQAEnmKC-Dtt9aD' \
  -H 'Authorization: Bearer <api_token>'

# Response

A successful request returns a 204 No Content status code. The API deletes the project grant and returns an empty response body.

# List customer workspace project grants

Retrieves a list of project grants from an Embedded customer workspace.

GET /api/managed_users/:managed_user_id/:id/project_grants

# Path parameters

Name	Type	Description
managed_user_id	string required	The Embedded customer ID or external ID. External IDs must be URL encoded and prefixed with an `E`, for example: `EA2300`.
id	string required	The ID of the project to retrieve grants from.

# Query parameters

Name	Type	Description
page[number]	integer optional	The page number to retrieve. The default value is `1`.
page[size]	integer optional	The number of items per page to retrieve. The default and maximum value is `100`.

# Sample request

curl -X GET 'https://www.workato.com/api/managed_users/19029/178229/project_grants?page[number]=1&page[size]=100' \
  -H 'Authorization: Bearer <api_token>'

# Response

{
  "data": [
    { 
      "id": "pg-AQAEnmMX-b4rPeT", 
      "project_role": { 
        "id": "pr-AQAEnmK3-EQpeYM", 
        "name": "Developers"
      }, 
      "user": {
        "id": 1,
        "name" : "Jie",
        "email": "[email protected]"
      },
      "user_group": null
    },  
    {
      "id": "pg-AQAEnmKC-Dtt9aD", 
      "project_role": {
        "id": "pr-AQAEnmK3-EQpeYM", 
        "name": "Developers"
      },
      "user": null,
      "user_group": {
        "id": "am-WxEKCibh-dTXBtz",
        "name" : "Developers",
        "system": false
      }
    }
  ],
  "total": 2,
  "page": {
    "number": 1,
    "size": 100
  }
}

# Add or update customer workspace project grants

Adds or updates project grants for a project in an Embedded customer workspace. You can include a maximum of 100 grants in each request.

PUT /api/managed_users/:managed_user_id/projects/:id/project_grants

# Path parameters

Name	Type	Description
managed_user_id	string required	The Embedded customer ID or external ID. External IDs must be URL encoded and prefixed with an `E`, for example: `EA2300`.
id	string required	The ID of the project where you plan to add or update grants.

# Request body

Name	Type	Description
project_grants	object required	Defines project grants for the project.
project_grants[assignment_type]	string required	Specifies whether to assign the role to a workspace (`User`) or collaborator group (`UserGroup`).
project_grants[assignment_id]	string required	The ID of the target workspace or collaborator group.
project_grants[project_role_id]	string required	The ID of the role to assign.

# Sample request

curl -X PUT 'https://www.workato.com/api/managed_users/19029/projects/178229/project_grants' \
  -H 'Authorization: Bearer <api_token>' \
  -H 'Content-Type: application/json' \
  -d '{
        "project_grants": [
          {
            "assignment_type": "User",
            "assignment_id": "1",
            "project_role_id": "pr-AQAEnmK3-EQpeYM"
          },
          {
            "assignment_type": "UserGroup",
            "assignment_id": "am-WxEKCibh-dTXBtz",
            "project_role_id": "pr-AQAEnmK3-EQpeYM"
          }
        ]
      }'

# Response

A successful request returns { "data": null }. This response indicates the operation succeeded, but no additional data is returned.

400 BAD REQUEST

In the following example, the request fails because it includes more than 100 grants:

{
  "errors": [
    {
      "code": "bad_request",
      "title": "Max 100 project grants per request"
    }
  ]
}

Last updated: 9/9/2025, 9:11:00 PM