diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
index 7e9d7756..71718a91 100644
--- a/docs/.vitepress/config.mts
+++ b/docs/.vitepress/config.mts
@@ -1026,6 +1026,43 @@ export default extendConfig(
{ text: "Get Current User", link: "/api-reference/user/get-current-user" },
],
},
+ {
+ text: "IDP Group Sync",
+ collapsed: true,
+ items: [
+ { text: "Overview", link: "/api-reference/idp-group-sync/overview" },
+ { text: "Get Group Sync Config", link: "/api-reference/idp-group-sync/get-group-sync-config" },
+ {
+ text: "Update Group Sync Config",
+ link: "/api-reference/idp-group-sync/update-group-sync-config",
+ },
+ { text: "List Project Mappings", link: "/api-reference/idp-group-sync/list-project-mappings" },
+ { 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: "Delete Project Mapping", link: "/api-reference/idp-group-sync/delete-project-mapping" },
+ {
+ text: "List Workspace Mappings",
+ link: "/api-reference/idp-group-sync/list-workspace-mappings",
+ },
+ {
+ text: "Create Workspace Mapping",
+ link: "/api-reference/idp-group-sync/create-workspace-mapping",
+ },
+ {
+ text: "Get Workspace Mapping",
+ link: "/api-reference/idp-group-sync/get-workspace-mapping",
+ },
+ {
+ text: "Update Workspace Mapping",
+ link: "/api-reference/idp-group-sync/update-workspace-mapping",
+ },
+ {
+ text: "Delete Workspace Mapping",
+ link: "/api-reference/idp-group-sync/delete-workspace-mapping",
+ },
+ ],
+ },
],
},
],
diff --git a/docs/api-reference/idp-group-sync/create-project-mapping.md b/docs/api-reference/idp-group-sync/create-project-mapping.md
new file mode 100644
index 00000000..2cef1647
--- /dev/null
+++ b/docs/api-reference/idp-group-sync/create-project-mapping.md
@@ -0,0 +1,153 @@
+---
+title: Create project group mapping
+description: Create a project group mapping via Plane API. HTTP request format, parameters, scopes, and example responses for create project group mapping.
+keywords: plane, plane api, rest api, api integration, idp group sync, create project group mapping
+---
+
+# Create project group mapping
+
+
+ POST
+ /api/v1/workspaces/{workspace_slug}/group-sync/project-mappings/
+
+
+
+
+
+Create a new IdP group → project mapping. Use `project` to map to a specific project, or `all_projects: true` to map to all projects in the workspace. These two fields are mutually exclusive.
+
+
+
+### 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`.
+
+
+
+
+
+
+
+
+### 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`
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X POST \
+ "https://api.plane.so/api/v1/workspaces/my-workspace/group-sync/project-mappings/" \
+ -H "X-API-Key: $PLANE_API_KEY" \
+ # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "idp_group_name": "engineering",
+ "project": "ENG",
+ "role": "member"
+}'
+```
+
+
+
+
+```python
+import requests
+
+response = requests.post(
+ "https://api.plane.so/api/v1/workspaces/my-workspace/group-sync/project-mappings/",
+ headers={"X-API-Key": "your-api-key"},
+ json={
+ "idp_group_name": "engineering",
+ "project": "ENG",
+ "role": "member"
+ }
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch("https://api.plane.so/api/v1/workspaces/my-workspace/group-sync/project-mappings/", {
+ method: "POST",
+ headers: {
+ "X-API-Key": "your-api-key",
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ idp_group_name: "engineering",
+ project: "ENG",
+ role: "member",
+ }),
+});
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "id": "661f9511-f30c-52e5-b827-557766551111",
+ "idp_group_name": "engineering",
+ "project": "ENG",
+ "all_projects": false,
+ "role": "member",
+ "created_at": "2024-01-01T00:00:00Z",
+ "updated_at": "2024-01-01T00:00:00Z"
+}
+```
+
+
+
+
+
+
+ POST
+ /api/v1/workspaces/{workspace_slug}/group-sync/workspace-mappings/
+
+
+
+
+
+Create a new IdP group → workspace role mapping.
+
+
+
+### 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`.
+
+
+
+
+
+
+
+
+### Body Parameters
+
+
+
+
+
+The name of the IdP group to map.
+
+
+
+
+
+Workspace role slug to assign to members of the IdP group (e.g. `member`, `admin`).
+
+
+
+
+
+
+
+
+### Scopes
+
+`workspaces.group_sync:write`
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X POST \
+ "https://api.plane.so/api/v1/workspaces/my-workspace/group-sync/workspace-mappings/" \
+ -H "X-API-Key: $PLANE_API_KEY" \
+ # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "idp_group_name": "leadership",
+ "role": "admin"
+}'
+```
+
+
+
+
+```python
+import requests
+
+response = requests.post(
+ "https://api.plane.so/api/v1/workspaces/my-workspace/group-sync/workspace-mappings/",
+ headers={"X-API-Key": "your-api-key"},
+ json={
+ "idp_group_name": "leadership",
+ "role": "admin"
+ }
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch("https://api.plane.so/api/v1/workspaces/my-workspace/group-sync/workspace-mappings/", {
+ method: "POST",
+ headers: {
+ "X-API-Key": "your-api-key",
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ idp_group_name: "leadership",
+ role: "admin",
+ }),
+});
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "id": "772g0622-g41d-63f6-c938-668877662222",
+ "idp_group_name": "leadership",
+ "role": "admin",
+ "created_at": "2024-01-01T00:00:00Z",
+ "updated_at": "2024-01-01T00:00:00Z"
+}
+```
+
+
+
+
+
+
+ DELETE
+ /api/v1/workspaces/{workspace_slug}/group-sync/project-mappings/{mapping_id}/
+
+
+
+
+
+Delete an IdP group → project mapping.
+
+
+
+### 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 unique identifier of the project group mapping.
+
+
+
+
+
+
+
+
+### Scopes
+
+`workspaces.group_sync:write`
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X DELETE \
+ "https://api.plane.so/api/v1/workspaces/my-workspace/group-sync/project-mappings/661f9511-f30c-52e5-b827-557766551111/" \
+ -H "X-API-Key: $PLANE_API_KEY"
+ # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.delete(
+ "https://api.plane.so/api/v1/workspaces/my-workspace/group-sync/project-mappings/661f9511-f30c-52e5-b827-557766551111/",
+ headers={"X-API-Key": "your-api-key"}
+)
+print(response.status_code)
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v1/workspaces/my-workspace/group-sync/project-mappings/661f9511-f30c-52e5-b827-557766551111/",
+ {
+ method: "DELETE",
+ headers: {
+ "X-API-Key": "your-api-key",
+ },
+ }
+);
+console.log(response.status);
+```
+
+
+
+
+
+
+No response body.
+
+
+
+
+
+
+ DELETE
+ /api/v1/workspaces/{workspace_slug}/group-sync/workspace-mappings/{mapping_id}/
+
+
+
+
+
+Delete an IdP group → workspace role mapping.
+
+
+
+### 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 unique identifier of the workspace group mapping.
+
+
+
+
+
+
+
+
+### Scopes
+
+`workspaces.group_sync:write`
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X DELETE \
+ "https://api.plane.so/api/v1/workspaces/my-workspace/group-sync/workspace-mappings/772g0622-g41d-63f6-c938-668877662222/" \
+ -H "X-API-Key: $PLANE_API_KEY"
+ # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.delete(
+ "https://api.plane.so/api/v1/workspaces/my-workspace/group-sync/workspace-mappings/772g0622-g41d-63f6-c938-668877662222/",
+ headers={"X-API-Key": "your-api-key"}
+)
+print(response.status_code)
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v1/workspaces/my-workspace/group-sync/workspace-mappings/772g0622-g41d-63f6-c938-668877662222/",
+ {
+ method: "DELETE",
+ headers: {
+ "X-API-Key": "your-api-key",
+ },
+ }
+);
+console.log(response.status);
+```
+
+
+
+
+
+
+No response body.
+
+
+
+
+
+
+ GET
+ /api/v1/workspaces/{workspace_slug}/group-sync/config/
+
+
+
+
+
+Retrieve the IdP group sync configuration for the workspace. Auto-creates the config with defaults on first access.
+
+
+
+### 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`.
+
+
+
+
+
+
+
+
+### Response Attributes
+
+
+
+
+
+Unique identifier of the config.
+
+
+
+
+
+Whether IdP group sync is enabled for the workspace.
+
+
+
+
+
+Sync group memberships automatically on user login.
+
+
+
+
+
+Automatically remove users from projects or workspace when removed from their IdP group.
+
+
+
+
+
+Allow sync to run outside of login events.
+
+
+
+
+
+The IdP claim key that contains group membership data (e.g. `groups`).
+
+
+
+
+
+Role slug assigned to users when added to the workspace via group sync.
+
+
+
+
+
+The timestamp of when the config was created.
+
+
+
+
+
+The timestamp of when the config was last updated.
+
+
+
+
+
+
+
+
+### Scopes
+
+`workspaces.group_sync:read`
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X GET \
+ "https://api.plane.so/api/v1/workspaces/my-workspace/group-sync/config/" \
+ -H "X-API-Key: $PLANE_API_KEY"
+ # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.get(
+ "https://api.plane.so/api/v1/workspaces/my-workspace/group-sync/config/",
+ headers={"X-API-Key": "your-api-key"}
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch("https://api.plane.so/api/v1/workspaces/my-workspace/group-sync/config/", {
+ headers: {
+ "X-API-Key": "your-api-key",
+ },
+});
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "id": "550e8400-e29b-41d4-a716-446655440000",
+ "is_enabled": true,
+ "sync_on_login": true,
+ "auto_remove": false,
+ "sync_offline": false,
+ "group_attribute_key": "groups",
+ "default_workspace_role": "member",
+ "created_at": "2024-01-01T00:00:00Z",
+ "updated_at": "2024-01-01T00:00:00Z"
+}
+```
+
+
+
+
+
+
+ GET
+ /api/v1/workspaces/{workspace_slug}/group-sync/project-mappings/{mapping_id}/
+
+
+
+
+
+Retrieve a single IdP group → project mapping by its ID.
+
+
+
+### 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 unique identifier of the project group mapping.
+
+
+
+
+
+
+
+
+### Response Attributes
+
+
+
+
+
+Unique identifier of the mapping.
+
+
+
+
+
+The name of the IdP group.
+
+
+
+
+
+Project identifier the group is mapped to. `null` when `all_projects` is `true`.
+
+
+
+
+
+Whether the group is mapped to all projects in the workspace.
+
+
+
+
+
+Role slug assigned to group members within the project.
+
+
+
+
+
+The timestamp of when the mapping was created.
+
+
+
+
+
+The timestamp of when the mapping was last updated.
+
+
+
+
+
+
+
+
+### Scopes
+
+`workspaces.group_sync:read`
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X GET \
+ "https://api.plane.so/api/v1/workspaces/my-workspace/group-sync/project-mappings/661f9511-f30c-52e5-b827-557766551111/" \
+ -H "X-API-Key: $PLANE_API_KEY"
+ # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.get(
+ "https://api.plane.so/api/v1/workspaces/my-workspace/group-sync/project-mappings/661f9511-f30c-52e5-b827-557766551111/",
+ headers={"X-API-Key": "your-api-key"}
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v1/workspaces/my-workspace/group-sync/project-mappings/661f9511-f30c-52e5-b827-557766551111/",
+ {
+ headers: {
+ "X-API-Key": "your-api-key",
+ },
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "id": "661f9511-f30c-52e5-b827-557766551111",
+ "idp_group_name": "engineering",
+ "project": "ENG",
+ "all_projects": false,
+ "role": "member",
+ "created_at": "2024-01-01T00:00:00Z",
+ "updated_at": "2024-01-01T00:00:00Z"
+}
+```
+
+
+
+
+
+
+ GET
+ /api/v1/workspaces/{workspace_slug}/group-sync/workspace-mappings/{mapping_id}/
+
+
+
+
+
+Retrieve a single IdP group → workspace role mapping by its ID.
+
+
+
+### 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 unique identifier of the workspace group mapping.
+
+
+
+
+
+
+
+
+### Response Attributes
+
+
+
+
+
+Unique identifier of the mapping.
+
+
+
+
+
+The name of the IdP group.
+
+
+
+
+
+Role slug assigned to group members within the workspace.
+
+
+
+
+
+The timestamp of when the mapping was created.
+
+
+
+
+
+The timestamp of when the mapping was last updated.
+
+
+
+
+
+
+
+
+### Scopes
+
+`workspaces.group_sync:read`
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X GET \
+ "https://api.plane.so/api/v1/workspaces/my-workspace/group-sync/workspace-mappings/772g0622-g41d-63f6-c938-668877662222/" \
+ -H "X-API-Key: $PLANE_API_KEY"
+ # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.get(
+ "https://api.plane.so/api/v1/workspaces/my-workspace/group-sync/workspace-mappings/772g0622-g41d-63f6-c938-668877662222/",
+ headers={"X-API-Key": "your-api-key"}
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v1/workspaces/my-workspace/group-sync/workspace-mappings/772g0622-g41d-63f6-c938-668877662222/",
+ {
+ headers: {
+ "X-API-Key": "your-api-key",
+ },
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "id": "772g0622-g41d-63f6-c938-668877662222",
+ "idp_group_name": "leadership",
+ "role": "admin",
+ "created_at": "2024-01-01T00:00:00Z",
+ "updated_at": "2024-01-01T00:00:00Z"
+}
+```
+
+
+
+
+
+
+ GET
+ /api/v1/workspaces/{workspace_slug}/group-sync/project-mappings/
+
+
+
+
+
+Retrieve all IdP group → project mappings for the workspace.
+
+
+
+### 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`.
+
+
+
+
+
+
+
+
+### Response Attributes
+
+
+
+
+
+Unique identifier of the mapping.
+
+
+
+
+
+The name of the IdP group.
+
+
+
+
+
+Project identifier the group is mapped to. `null` when `all_projects` is `true`.
+
+
+
+
+
+Whether the group is mapped to all projects in the workspace.
+
+
+
+
+
+Role slug assigned to group members within the project.
+
+
+
+
+
+The timestamp of when the mapping was created.
+
+
+
+
+
+The timestamp of when the mapping was last updated.
+
+
+
+
+
+
+
+
+### Scopes
+
+`workspaces.group_sync:read`
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X GET \
+ "https://api.plane.so/api/v1/workspaces/my-workspace/group-sync/project-mappings/" \
+ -H "X-API-Key: $PLANE_API_KEY"
+ # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.get(
+ "https://api.plane.so/api/v1/workspaces/my-workspace/group-sync/project-mappings/",
+ headers={"X-API-Key": "your-api-key"}
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch("https://api.plane.so/api/v1/workspaces/my-workspace/group-sync/project-mappings/", {
+ headers: {
+ "X-API-Key": "your-api-key",
+ },
+});
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+[
+ {
+ "id": "661f9511-f30c-52e5-b827-557766551111",
+ "idp_group_name": "engineering",
+ "project": "ENG",
+ "all_projects": false,
+ "role": "member",
+ "created_at": "2024-01-01T00:00:00Z",
+ "updated_at": "2024-01-01T00:00:00Z"
+ },
+ {
+ "id": "772g0622-g41d-63f6-c938-668877662222",
+ "idp_group_name": "all-staff",
+ "project": null,
+ "all_projects": true,
+ "role": "guest",
+ "created_at": "2024-01-01T00:00:00Z",
+ "updated_at": "2024-01-01T00:00:00Z"
+ }
+]
+```
+
+
+
+
+
+
+ GET
+ /api/v1/workspaces/{workspace_slug}/group-sync/workspace-mappings/
+
+
+
+
+
+Retrieve all IdP group → workspace role mappings for the workspace.
+
+
+
+### 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`.
+
+
+
+
+
+
+
+
+### Response Attributes
+
+
+
+
+
+Unique identifier of the mapping.
+
+
+
+
+
+The name of the IdP group.
+
+
+
+
+
+Role slug assigned to group members within the workspace.
+
+
+
+
+
+The timestamp of when the mapping was created.
+
+
+
+
+
+The timestamp of when the mapping was last updated.
+
+
+
+
+
+
+
+
+### Scopes
+
+`workspaces.group_sync:read`
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X GET \
+ "https://api.plane.so/api/v1/workspaces/my-workspace/group-sync/workspace-mappings/" \
+ -H "X-API-Key: $PLANE_API_KEY"
+ # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.get(
+ "https://api.plane.so/api/v1/workspaces/my-workspace/group-sync/workspace-mappings/",
+ headers={"X-API-Key": "your-api-key"}
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch("https://api.plane.so/api/v1/workspaces/my-workspace/group-sync/workspace-mappings/", {
+ headers: {
+ "X-API-Key": "your-api-key",
+ },
+});
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+[
+ {
+ "id": "772g0622-g41d-63f6-c938-668877662222",
+ "idp_group_name": "leadership",
+ "role": "admin",
+ "created_at": "2024-01-01T00:00:00Z",
+ "updated_at": "2024-01-01T00:00:00Z"
+ },
+ {
+ "id": "883h1733-h52e-74g7-d049-779988773333",
+ "idp_group_name": "engineering",
+ "role": "member",
+ "created_at": "2024-01-01T00:00:00Z",
+ "updated_at": "2024-01-01T00:00:00Z"
+ }
+]
+```
+
+
+
+
+
+
+
+
+### The Group Sync Config Object
+
+### Attributes
+
+- `id` _uuid_
+
+ Unique identifier of the config.
+
+- `is_enabled` _boolean_
+
+ Whether IdP group sync is enabled for the workspace.
+
+- `sync_on_login` _boolean_
+
+ Sync group memberships automatically on user login.
+
+- `auto_remove` _boolean_
+
+ Automatically remove users from projects/workspace when they are removed from the IdP group.
+
+- `sync_offline` _boolean_
+
+ Allow sync to run outside of login events.
+
+- `group_attribute_key` _string_
+
+ The IdP claim key that contains group membership data (e.g. `groups`).
+
+- `default_workspace_role` _string_
+
+ Role slug assigned to users when added to the workspace via group sync.
+
+- `created_at` _timestamp_
+
+ The timestamp of when the config was created.
+
+- `updated_at` _timestamp_
+
+ The timestamp of when the config was last updated.
+
+### The Project Group Mapping Object
+
+### Attributes
+
+- `id` _uuid_
+
+ Unique identifier of the mapping.
+
+- `idp_group_name` _string_
+
+ The name of the IdP group to map.
+
+- `project` _string_
+
+ Project identifier the group is mapped to. Mutually exclusive with `all_projects`.
+
+- `all_projects` _boolean_
+
+ When `true`, maps the group to all projects in the workspace. Mutually exclusive with `project`.
+
+- `role` _string_
+
+ Role slug assigned to group members within the project.
+
+- `created_at` _timestamp_
+
+ The timestamp of when the mapping was created.
+
+- `updated_at` _timestamp_
+
+ The timestamp of when the mapping was last updated.
+
+### The Workspace Group Mapping Object
+
+### Attributes
+
+- `id` _uuid_
+
+ Unique identifier of the mapping.
+
+- `idp_group_name` _string_
+
+ The name of the IdP group to map.
+
+- `role` _string_
+
+ Role slug assigned to group members within the workspace.
+
+- `created_at` _timestamp_
+
+ The timestamp of when the mapping was created.
+
+- `updated_at` _timestamp_
+
+ The timestamp of when the mapping was last updated.
+
+
+
+
+
+
+```json
+{
+ "id": "550e8400-e29b-41d4-a716-446655440000",
+ "is_enabled": true,
+ "sync_on_login": true,
+ "auto_remove": false,
+ "sync_offline": false,
+ "group_attribute_key": "groups",
+ "default_workspace_role": "member",
+ "created_at": "2024-01-01T00:00:00Z",
+ "updated_at": "2024-01-01T00:00:00Z"
+}
+```
+
+
+
+
+
+```json
+{
+ "id": "661f9511-f30c-52e5-b827-557766551111",
+ "idp_group_name": "engineering",
+ "project": "ENG",
+ "all_projects": false,
+ "role": "member",
+ "created_at": "2024-01-01T00:00:00Z",
+ "updated_at": "2024-01-01T00:00:00Z"
+}
+```
+
+
+
+
+
+```json
+{
+ "id": "772g0622-g41d-63f6-c938-668877662222",
+ "idp_group_name": "leadership",
+ "role": "admin",
+ "created_at": "2024-01-01T00:00:00Z",
+ "updated_at": "2024-01-01T00:00:00Z"
+}
+```
+
+
+
+
+
+ PATCH
+ /api/v1/workspaces/{workspace_slug}/group-sync/config/
+
+
+
+
+
+Update the IdP group sync configuration for the workspace. Supports partial updates — only include fields you want to change.
+
+
+
+### 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`.
+
+
+
+
+
+
+
+
+### Body Parameters
+
+
+
+
+
+Enable or disable IdP group sync for the workspace.
+
+
+
+
+
+Sync group memberships automatically on user login.
+
+
+
+
+
+Automatically remove users from projects or workspace when removed from their IdP group.
+
+
+
+
+
+Allow sync to run outside of login events.
+
+
+
+
+
+The IdP claim key that contains group membership data (e.g. `groups`).
+
+
+
+
+
+Role slug assigned to users when added to the workspace via group sync.
+
+
+
+
+
+
+
+
+### Scopes
+
+`workspaces.group_sync:write`
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X PATCH \
+ "https://api.plane.so/api/v1/workspaces/my-workspace/group-sync/config/" \
+ -H "X-API-Key: $PLANE_API_KEY" \
+ # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "is_enabled": true,
+ "sync_on_login": true,
+ "auto_remove": false,
+ "sync_offline": false,
+ "group_attribute_key": "groups",
+ "default_workspace_role": "member"
+}'
+```
+
+
+
+
+```python
+import requests
+
+response = requests.patch(
+ "https://api.plane.so/api/v1/workspaces/my-workspace/group-sync/config/",
+ headers={"X-API-Key": "your-api-key"},
+ json={
+ "is_enabled": True,
+ "sync_on_login": True,
+ "auto_remove": False,
+ "sync_offline": False,
+ "group_attribute_key": "groups",
+ "default_workspace_role": "member"
+ }
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch("https://api.plane.so/api/v1/workspaces/my-workspace/group-sync/config/", {
+ method: "PATCH",
+ headers: {
+ "X-API-Key": "your-api-key",
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ is_enabled: true,
+ sync_on_login: true,
+ auto_remove: false,
+ sync_offline: false,
+ group_attribute_key: "groups",
+ default_workspace_role: "member",
+ }),
+});
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "id": "550e8400-e29b-41d4-a716-446655440000",
+ "is_enabled": true,
+ "sync_on_login": true,
+ "auto_remove": false,
+ "sync_offline": false,
+ "group_attribute_key": "groups",
+ "default_workspace_role": "member",
+ "created_at": "2024-01-01T00:00:00Z",
+ "updated_at": "2024-01-01T00:00:00Z"
+}
+```
+
+
+
+
+
+
+ PATCH
+ /api/v1/workspaces/{workspace_slug}/group-sync/project-mappings/{mapping_id}/
+
+
+
+
+
+Update an existing IdP group → project mapping. Supports partial updates.
+
+
+
+### 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 unique identifier of the project group mapping.
+
+
+
+
+
+
+
+
+### 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`
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X PATCH \
+ "https://api.plane.so/api/v1/workspaces/my-workspace/group-sync/project-mappings/661f9511-f30c-52e5-b827-557766551111/" \
+ -H "X-API-Key: $PLANE_API_KEY" \
+ # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "role": "admin"
+}'
+```
+
+
+
+
+```python
+import requests
+
+response = requests.patch(
+ "https://api.plane.so/api/v1/workspaces/my-workspace/group-sync/project-mappings/661f9511-f30c-52e5-b827-557766551111/",
+ headers={"X-API-Key": "your-api-key"},
+ json={"role": "admin"}
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v1/workspaces/my-workspace/group-sync/project-mappings/661f9511-f30c-52e5-b827-557766551111/",
+ {
+ method: "PATCH",
+ headers: {
+ "X-API-Key": "your-api-key",
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({ role: "admin" }),
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```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"
+}
+```
+
+
+
+
+
+
+ PATCH
+ /api/v1/workspaces/{workspace_slug}/group-sync/workspace-mappings/{mapping_id}/
+
+
+
+
+
+Update an existing IdP group → workspace role mapping. Supports partial updates.
+
+
+
+### 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 unique identifier of the workspace group mapping.
+
+
+
+
+
+
+
+
+### Body Parameters
+
+
+
+
+
+The name of the IdP group to map.
+
+
+
+
+
+Workspace role slug to assign to members of the IdP group (e.g. `member`, `admin`).
+
+
+
+
+
+
+
+
+### Scopes
+
+`workspaces.group_sync:write`
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X PATCH \
+ "https://api.plane.so/api/v1/workspaces/my-workspace/group-sync/workspace-mappings/772g0622-g41d-63f6-c938-668877662222/" \
+ -H "X-API-Key: $PLANE_API_KEY" \
+ # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "role": "member"
+}'
+```
+
+
+
+
+```python
+import requests
+
+response = requests.patch(
+ "https://api.plane.so/api/v1/workspaces/my-workspace/group-sync/workspace-mappings/772g0622-g41d-63f6-c938-668877662222/",
+ headers={"X-API-Key": "your-api-key"},
+ json={"role": "member"}
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v1/workspaces/my-workspace/group-sync/workspace-mappings/772g0622-g41d-63f6-c938-668877662222/",
+ {
+ method: "PATCH",
+ headers: {
+ "X-API-Key": "your-api-key",
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({ role: "member" }),
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "id": "772g0622-g41d-63f6-c938-668877662222",
+ "idp_group_name": "leadership",
+ "role": "member",
+ "created_at": "2024-01-01T00:00:00Z",
+ "updated_at": "2024-01-01T00:00:00Z"
+}
+```
+
+
+
+
+
+