> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nekt.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Update a Permission Group

> Rename a group, or replace its membership wholesale.

Changes a group's name, description, or membership. Send only the fields you are changing.

## Request body

| Parameter     | Type              | Description                         |
| ------------- | ----------------- | ----------------------------------- |
| `name`        | string            | The group's name.                   |
| `description` | string            | What the group is for.              |
| `users`       | array of integers | **Replaces** the entire membership. |

<Warning>
  `users` is a replacement, not an addition. Sending `{"users": [7]}` to a group of twelve leaves one person in it, and the other eleven lose every grant that reached them through the group. To add or remove a few people without touching the rest, use [Add Members](/platform-api/permission-groups/add-members) and [Remove Members](/platform-api/permission-groups/remove-members).
</Warning>

## Rename a group

```bash theme={null}
curl --request PATCH \
  --url https://api.nekt.ai/api/v1/organization/permission-groups/GROUP_ID/ \
  --header "x-api-key: YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"name": "Data Analysts"}'
```

Renaming changes nothing about access. Grants point at the group's id.

## Replace a membership

Useful when your own system is the source of truth for a team and you are syncing it across, rather than tracking individual joins and leaves.

```python theme={null}
import os

import requests

BASE_URL = "https://api.nekt.ai"
headers = {"x-api-key": os.environ["NEKT_API_KEY"], "Content-Type": "application/json"}

# Whoever is on the team right now, per your HR system.
current_team = [12, 42, 57]

response = requests.patch(
    f"{BASE_URL}/api/v1/organization/permission-groups/GROUP_ID/",
    headers=headers,
    json={"users": current_team},
)
response.raise_for_status()
```

Anybody dropped from the list loses the group's grants immediately, and anybody added gains them — no permission call either way.

## Response

`200`, with the updated [permission group object](/platform-api/permission-groups/permission-group).

## Errors

| Status | When                                                                                 |
| ------ | ------------------------------------------------------------------------------------ |
| `400`  | A user id in `users` belongs to a deactivated member.                                |
| `400`  | You are renaming the All group, or setting its `users`. Its membership is automatic. |
| `403`  | Your API key was created by a Member.                                                |
| `404`  | No group with that id in your workspace.                                             |

<Note>
  `PUT` is also available and replaces every writable field at once. `PATCH` is what you usually want.
</Note>

## Related

* [Add Members](/platform-api/permission-groups/add-members) — adjusting membership instead of replacing it.
* [The All group](/platform-api/permission-groups/overview#the-all-group) — what cannot be changed.


## OpenAPI

````yaml PATCH /api/v1/organization/permission-groups/{id}/
openapi: 3.0.3
info:
  title: Nekt API
  version: v1
  description: Nekt API Documentation
  contact:
    email: support@nekt.ai
servers:
  - url: https://api.nekt.ai
security: []
paths:
  /api/v1/organization/permission-groups/{id}/:
    patch:
      tags:
        - v1
      summary: Update a permission group
      operationId: v1_organization_permission_groups_partial_update
      parameters:
        - in: path
          name: id
          schema:
            type: string
            format: uuid
          description: The permission group's id.
          required: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchedPermissionGroup'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/PatchedPermissionGroup'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/PatchedPermissionGroup'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PermissionGroup'
          description: ''
      security:
        - ApiKeyAuth: []
components:
  schemas:
    PatchedPermissionGroup:
      type: object
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        name:
          type: string
          maxLength: 150
        description:
          type: string
          nullable: true
        all_group:
          type: boolean
          readOnly: true
        created_at:
          type: string
          format: date-time
          readOnly: true
        updated_at:
          type: string
          format: date-time
          readOnly: true
        users:
          type: array
          items:
            type: integer
          description: Users (Expandable)
    PermissionGroup:
      type: object
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        name:
          type: string
          maxLength: 150
        description:
          type: string
          nullable: true
        all_group:
          type: boolean
          readOnly: true
        created_at:
          type: string
          format: date-time
          readOnly: true
        updated_at:
          type: string
          format: date-time
          readOnly: true
        users:
          type: array
          items:
            type: integer
          description: Users (Expandable)
      required:
        - all_group
        - created_at
        - id
        - name
        - updated_at
        - users
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: 'API Key authentication. Format: ''x-api-key: api_key'''

````