> ## 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.

# Create a Permission Group

> A new group, optionally with its members already in it.

Creates a permission group. A new group holds no grants — make them with the [Permissions API](/platform-api/permissions/overview) once the group exists.

## Request body

| Parameter     | Type              | Required | Description                                                                                     |
| ------------- | ----------------- | -------- | ----------------------------------------------------------------------------------------------- |
| `name`        | string            | Yes      | Shown wherever the group appears. Pick something a colleague will recognize in a grant listing. |
| `description` | string            | No       | What the group is for.                                                                          |
| `users`       | array of integers | No       | User ids to put in the group immediately.                                                       |

```bash theme={null}
curl --request POST \
  --url https://api.nekt.ai/api/v1/organization/permission-groups/ \
  --header "x-api-key: YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Analysts",
    "description": "Read access to the Gold layer",
    "users": [12, 42]
  }'
```

<Note>
  `users` takes **user ids**, which are integers, not the UUIDs used to identify groups and resources. Get them from [List Recipients](/platform-api/permissions/catalog/recipients).
</Note>

## Response

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

```json theme={null}
{
  "id": "c1f0a9d4-5b62-4e18-9a73-2d8e4f6b0c51",
  "name": "Analysts",
  "description": "Read access to the Gold layer",
  "all_group": false,
  "created_at": "2026-09-25T10:14:02Z",
  "updated_at": "2026-09-25T10:14:02Z",
  "users": [12, 42]
}
```

## Create a team and grant it access

The two calls that set a team up. After this, onboarding anybody onto that team is one membership call.

```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"}

group = requests.post(
    f"{BASE_URL}/api/v1/organization/permission-groups/",
    headers=headers,
    json={"name": "Analysts", "description": "Read access to the Gold layer"},
)
group.raise_for_status()
group_id = group.json()["id"]

grant = requests.post(
    f"{BASE_URL}/api/v1/permissions/",
    headers=headers,
    json={
        "assignments": [
            {"permission_level": "viewer", "groups": [group_id], "layers": ["LAYER_ID"]}
        ]
    },
)
grant.raise_for_status()
```

## Errors

| Status | When                                                                                      |
| ------ | ----------------------------------------------------------------------------------------- |
| `400`  | A user id in `users` belongs to a deactivated member.                                     |
| `403`  | Your API key was created by a Member. Creating groups requires an Owner's or Admin's key. |

## Related

* [Assign Permissions](/platform-api/permissions/catalog/assign) — giving the new group its access.
* [Add Members](/platform-api/permission-groups/add-members) — filling it later.
* [Permission groups](/platform-api/permission-groups/overview) — why a group instead of direct grants.


## OpenAPI

````yaml POST /api/v1/organization/permission-groups/
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/:
    post:
      tags:
        - v1
      summary: Create a permission group
      operationId: v1_organization_permission_groups_create
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PermissionGroup'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/PermissionGroup'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/PermissionGroup'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PermissionGroup'
          description: ''
      security:
        - ApiKeyAuth: []
components:
  schemas:
    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'''

````