Project grants

Use the following endpoints to manage a collaborator or group's project grants.

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/project_grants/:id	Get a project grant.
PUT	/api/project_grants/:id	Update a project grant.
DELETE	/api/project_grants/:id	Delete a project grant.
GET	/api/projects/:id/project_grants	List project grants.
PUT	/api/projects/:id/project_grants	Add or update project grants.

Get a project grant

Retrieves a project grant by its ID.

GET /api/project_grants/:id

Path parameters

Name	Type	Description
id	string required	The ID of the project grant to retrieve.

Sample request

curl -X GET 'https://www.workato.com/api/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 project grant

Updates an existing project grant by its ID.

PUT /api/project_grants/:id

Path parameters

Name	Type	Description
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/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 assignment is already taken:

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

Delete a project grant

Deletes a project grant by its ID.

DELETE /api/project_grants/:id

Path parameters

Name	Type	Description
id	string required	The ID of the project grant to delete.

Sample request

curl -X DELETE 'https://www.workato.com/api/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 project grants

Retrieves a list of grants from a project by its ID.

GET /api/projects/:id/project_grants

Path parameters

Name	Type	Description
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/projects/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 project grants

Adds or updates project grants for a project by its ID. You can include a maximum of 100 grants in each request.

PUT /api/projects/:id/project_grants

Path parameters

Name	Type	Description
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/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

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 it exceeds the maximum number of grants per request:

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