diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index 7d2ce701..2d4ebfca 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -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", diff --git a/docs/api-reference/idp-group-sync/list-project-mappings.md b/docs/api-reference/idp-group-sync/list-project-mappings.md index d597018f..217a1f88 100644 --- a/docs/api-reference/idp-group-sync/list-project-mappings.md +++ b/docs/api-reference/idp-group-sync/list-project-mappings.md @@ -14,7 +14,7 @@ keywords: plane, plane api, rest api, api integration, idp group sync, list proj
-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.
@@ -33,6 +33,21 @@ The workspace_slug represents the unique workspace identifier for a workspace in
+### Query Parameters + +
+ + + +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. + + + +
+
+ +
+ ### Response Attributes
diff --git a/docs/api-reference/idp-group-sync/update-project-mapping-by-key.md b/docs/api-reference/idp-group-sync/update-project-mapping-by-key.md new file mode 100644 index 00000000..b3d22afb --- /dev/null +++ b/docs/api-reference/idp-group-sync/update-project-mapping-by-key.md @@ -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 + +
+ PATCH + /api/v1/workspaces/{workspace_slug}/group-sync/project-mappings/{project_key}/{idp_group_name}/ +
+ +
+
+ +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."}`. + +
+ +### Path Parameters + +
+ + + +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`. + + + + + +The project identifier (e.g. `ENG`). Case-insensitive — the value is matched against the uppercase project identifier. + + + + + +The name of the IdP group the mapping belongs to. Matched exactly. + + + +
+
+ +
+ +### Body Parameters + +
+ + + +The name of the IdP group to map. + + + + + +Project role slug to assign to members of the IdP group (e.g. `member`, `admin`, `guest`). + + + + + +Project identifier to map the group to (e.g. `ENG`). Mutually exclusive with `all_projects`. + + + + + +When `true`, maps the group to all projects in the workspace. Mutually exclusive with `project`. + + + +
+
+ +
+ +### Scopes + +`workspaces.group_sync:write` + +
+ +
+ +
+ + + + + + + + + +```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" +} +``` + + + +
+ +
diff --git a/docs/api-reference/idp-group-sync/update-project-mapping.md b/docs/api-reference/idp-group-sync/update-project-mapping.md index 65540999..8fd47509 100644 --- a/docs/api-reference/idp-group-sync/update-project-mapping.md +++ b/docs/api-reference/idp-group-sync/update-project-mapping.md @@ -14,7 +14,9 @@ keywords: plane, plane api, rest api, api integration, idp group sync, update pr
-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).
diff --git a/docs/api-reference/idp-group-sync/update-workspace-mapping.md b/docs/api-reference/idp-group-sync/update-workspace-mapping.md index 87860bc7..0d47bd6a 100644 --- a/docs/api-reference/idp-group-sync/update-workspace-mapping.md +++ b/docs/api-reference/idp-group-sync/update-workspace-mapping.md @@ -14,7 +14,7 @@ keywords: plane, plane api, rest api, api integration, idp group sync, update wo
-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."}`.