Skip to content

docs: group-sync mapping filter, patch-by-project-key, empty-body 400 #307

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
pablohashescobar wants to merge 1 commit into
base: master
Choose a base branch
from
Open

docs: group-sync mapping filter, patch-by-project-key, empty-body 400 #307

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions docs/.vitepress/config.mts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1058,6 +1058,10 @@ export default extendConfig(
{ text: "Create Project Mapping", link: "/api-reference/idp-group-sync/create-project-mapping" },
{ text: "Get Project Mapping", link: "/api-reference/idp-group-sync/get-project-mapping" },
{ text: "Update Project Mapping", link: "/api-reference/idp-group-sync/update-project-mapping" },
{
text: "Update Project Mapping by Key",
link: "/api-reference/idp-group-sync/update-project-mapping-by-key",
},
{ text: "Delete Project Mapping", link: "/api-reference/idp-group-sync/delete-project-mapping" },
{
text: "List Workspace Mappings",
Expand Down
17 changes: 16 additions & 1 deletion docs/api-reference/idp-group-sync/list-project-mappings.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ keywords: plane, plane api, rest api, api integration, idp group sync, list proj
<div class="api-two-column">
<div class="api-left">

Retrieve all IdP group → project mappings for the workspace.
Retrieve all IdP group → project mappings for the workspace. Pass `project_identifier` to return only the mappings for a single project.

<div class="params-section">

Expand All @@ -33,6 +33,21 @@ The workspace_slug represents the unique workspace identifier for a workspace in

<div class="params-section">

### Query Parameters

<div class="params-list">

<ApiParam name="project_identifier" type="string" :required="false">

Filter mappings to a single project by its identifier (e.g. `ENG`). Case-insensitive — the value is matched against the uppercase project identifier. An unknown identifier returns an empty list.

</ApiParam>

</div>
</div>

<div class="params-section">

### Response Attributes

<div class="params-list">
Expand Down
162 changes: 162 additions & 0 deletions docs/api-reference/idp-group-sync/update-project-mapping-by-key.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,162 @@
---
title: Update project group mapping by key
description: Update a project group mapping by project identifier and IdP group name via Plane API. HTTP request format, parameters, scopes, and example responses.
keywords: plane, plane api, rest api, api integration, idp group sync, update project group mapping by key
---

# Update project group mapping by key

<div class="api-endpoint-badge">
<span class="method patch">PATCH</span>
<span class="path">/api/v1/workspaces/{workspace_slug}/group-sync/project-mappings/{project_key}/{idp_group_name}/</span>
</div>

<div class="api-two-column">
<div class="api-left">

Update an existing IdP group → project mapping addressed by its project identifier and IdP group name instead of the mapping ID. Because a project can have multiple mappings (one per IdP group), both keys are required to identify the target. Supports partial updates.

Only project-scoped mappings can be addressed this way. Mappings with `all_projects: true` have no project identifier — update those by mapping ID with [Update project group mapping](/api-reference/idp-group-sync/update-project-mapping).

Returns `404` when no project with the given identifier exists or the project has no mapping for the given IdP group name. An empty request body returns `400` with `{"error": "Request body cannot be empty."}`.

<div class="params-section">

### Path Parameters

<div class="params-list">

<ApiParam name="workspace_slug" type="string" :required="true">

The workspace_slug represents the unique workspace identifier for a workspace in Plane. It can be found in the URL. For example, in the URL `https://app.plane.so/my-team/projects/`, the workspace slug is `my-team`.

</ApiParam>

<ApiParam name="project_key" type="string" :required="true">

The project identifier (e.g. `ENG`). Case-insensitive — the value is matched against the uppercase project identifier.

</ApiParam>

<ApiParam name="idp_group_name" type="string" :required="true">

The name of the IdP group the mapping belongs to. Matched exactly.

</ApiParam>

</div>
</div>

<div class="params-section">

### Body Parameters

<div class="params-list">

<ApiParam name="idp_group_name" type="string" :required="false">

The name of the IdP group to map.

</ApiParam>

<ApiParam name="role" type="string" :required="false">

Project role slug to assign to members of the IdP group (e.g. `member`, `admin`, `guest`).

</ApiParam>

<ApiParam name="project" type="string" :required="false">

Project identifier to map the group to (e.g. `ENG`). Mutually exclusive with `all_projects`.

</ApiParam>

<ApiParam name="all_projects" type="boolean" :required="false">

When `true`, maps the group to all projects in the workspace. Mutually exclusive with `project`.

</ApiParam>

</div>
</div>

<div class="params-section">

### Scopes

`workspaces.group_sync:write`

</div>

</div>

<div class="api-right">

<CodePanel title="Update project group mapping by key" :languages="['cURL', 'Python', 'JavaScript']">
<template #curl>

```bash
curl -X PATCH \
"https://api.plane.so/api/v1/workspaces/my-workspace/group-sync/project-mappings/ENG/engineering/" \
-H "X-API-Key: $PLANE_API_KEY" \
# Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \
-H "Content-Type: application/json" \
Comment on lines +99 to +103

@coderabbitai coderabbitai Bot Aug 7, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Move the alternate authentication comment outside the continued command.

The API-key header line ends with \, so the shell continues into the next line. The # Or use ... comment then interrupts the command. A copied request can execute -H "Content-Type: application/json" as a separate command.

Move the comment above curl, or show the alternate authentication header in a separate complete command.

Suggested layout 
+# Use one authentication header:
+# -H "X-API-Key: $PLANE_API_KEY"
+# -H "Authorization: Bearer $PLANE_OAUTH_TOKEN"
 curl -X PATCH \
   "https://api.plane.so/api/v1/workspaces/my-workspace/group-sync/project-mappings/ENG/engineering/" \
   -H "X-API-Key: $PLANE_API_KEY" \
-  # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \
   -H "Content-Type: application/json" \
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
curl -X PATCH \
"https://api.plane.so/api/v1/workspaces/my-workspace/group-sync/project-mappings/ENG/engineering/" \
-H "X-API-Key: $PLANE_API_KEY" \
# Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \
-H "Content-Type: application/json" \
# Use one authentication header:
# -H "X-API-Key: $PLANE_API_KEY"
# -H "Authorization: Bearer $PLANE_OAUTH_TOKEN"
curl -X PATCH \
"https://api.plane.so/api/v1/workspaces/my-workspace/group-sync/project-mappings/ENG/engineering/" \
-H "X-API-Key: $PLANE_API_KEY" \
-H "Content-Type: application/json" \
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/api-reference/idp-group-sync/update-project-mapping-by-key.md` around
lines 99 - 103, Move the alternate OAuth authentication comment out of the
continued curl command in the documentation example, placing it before the curl
invocation or presenting it as a separate complete command. Ensure every line in
the primary command remains part of the same shell command without an
intervening comment.

-d '{
"role": "admin"
}'
```

</template>
<template #python>

```python
import requests

response = requests.patch(
"https://api.plane.so/api/v1/workspaces/my-workspace/group-sync/project-mappings/ENG/engineering/",
headers={"X-API-Key": "your-api-key"},
json={"role": "admin"}
)
print(response.json())
```

</template>
<template #javascript>

```javascript
const response = await fetch(
"https://api.plane.so/api/v1/workspaces/my-workspace/group-sync/project-mappings/ENG/engineering/",
{
method: "PATCH",
headers: {
"X-API-Key": "your-api-key",
"Content-Type": "application/json",
},
body: JSON.stringify({ role: "admin" }),
}
);
const data = await response.json();
```

</template>
</CodePanel>

<ResponsePanel status="200">

```json
{
"id": "661f9511-f30c-52e5-b827-557766551111",
"idp_group_name": "engineering",
"project": "ENG",
"all_projects": false,
"role": "admin",
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-01T00:00:00Z"
}
```

</ResponsePanel>

</div>

</div>
4 changes: 3 additions & 1 deletion docs/api-reference/idp-group-sync/update-project-mapping.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,9 @@ keywords: plane, plane api, rest api, api integration, idp group sync, update pr
<div class="api-two-column">
<div class="api-left">

Update an existing IdP group → project mapping. Supports partial updates.
Update an existing IdP group → project mapping. Supports partial updates. An empty request body returns `400` with `{"error": "Request body cannot be empty."}`.

To address a mapping by its project identifier and IdP group name instead of the mapping ID, see [Update project group mapping by key](/api-reference/idp-group-sync/update-project-mapping-by-key).

<div class="params-section">

Expand Down
2 changes: 1 addition & 1 deletion docs/api-reference/idp-group-sync/update-workspace-mapping.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ keywords: plane, plane api, rest api, api integration, idp group sync, update wo
<div class="api-two-column">
<div class="api-left">

Update an existing IdP group → workspace role mapping. Supports partial updates.
Update an existing IdP group → workspace role mapping. Supports partial updates. An empty request body returns `400` with `{"error": "Request body cannot be empty."}`.

<div class="params-section">

Expand Down
Loading