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

# Permission groups

> Grant access to a team once, and manage who is on the team.

A permission group is a named set of people that grants can be made to. Grant a group access to a layer, a secret, or a Semantic Layer folder, and everybody in the group has it — including anybody you add later.

This is what keeps access control proportional to the number of **teams** rather than the number of **people**. Onboard a new analyst by putting them in the Analysts group, and they inherit every grant that group holds, in one call, with no permission API involved.

<Info>
  Managing groups requires an [API key](https://app.nekt.ai/settings/api-keys) created by an **Owner** or an **Admin**. A key created by a Member can read groups but not change them. See [the ceiling rule](/platform-api/permissions/overview#the-ceiling-rule).
</Info>

***

## A group grant is live, not a snapshot

This is the property worth building on. A grant made to a group is evaluated through the group's membership every time, so:

* **Adding** somebody to the group gives them everything the group holds, immediately.
* **Removing** them takes it all back, immediately.

Neither requires a permission call. You change the membership; the access follows.

<Note>
  A person's effective access is the **union** of every grant that reaches them — their own grants plus every group they are in. Groups add access; they never subtract it.
</Note>

***

## Three ways to set membership

They all do the same thing. Pick whichever fits the shape of your script.

| When                                             | Use                                                                                                                             |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| Creating the group with its people already known | `users` on [Create a Group](/platform-api/permission-groups/create)                                                             |
| Replacing the whole membership                   | `users` on [Update a Group](/platform-api/permission-groups/update)                                                             |
| Adding or removing a few, leaving the rest alone | [Add Members](/platform-api/permission-groups/add-members) and [Remove Members](/platform-api/permission-groups/remove-members) |

The difference that matters: `users` on the group **replaces** the membership, while the members endpoints **adjust** it. Sending `{"users": [7]}` to a group of twelve leaves one person in it.

***

## Pending invitees count

Somebody who has been invited but has not accepted can be put in a group straight away, and the group's grants attach to them at that moment. That is what lets you finish an onboarding script on the day the contract is signed — see [Onboarding flow](/platform-api/invitations/overview).

***

## The All group

Every workspace has one group named **All**, marked `all_group: true`, which automatically contains every member. You can grant to it like any other group, but you cannot change it:

| Operation              | On the All group                |
| ---------------------- | ------------------------------- |
| Grant to it            | Works                           |
| Change its description | Works                           |
| Add or remove members  | `400` — membership is automatic |
| Rename it              | `400`                           |
| Delete it              | `400`                           |

Use it for access everybody should have. Anything narrower belongs in a group you create.

***

## Typical flow

<Steps>
  <Step title="Find or create the group">
    ```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"}'
    ```
  </Step>

  <Step title="Grant the group its access">
    Once, for the whole team. See [Permissions flow](/platform-api/permissions/overview).

    ```bash theme={null}
    curl --request POST \
      --url https://api.nekt.ai/api/v1/permissions/ \
      --header "x-api-key: YOUR_API_KEY" \
      --header "Content-Type: application/json" \
      --data '{
        "assignments": [
          {"permission_level": "viewer", "groups": ["GROUP_ID"], "layers": ["LAYER_ID"]}
        ]
      }'
    ```
  </Step>

  <Step title="Add people as they arrive">
    No permission call. The grants from step two reach them the moment they are in.

    ```bash theme={null}
    curl --request POST \
      --url https://api.nekt.ai/api/v1/organization/permission-groups/GROUP_ID/users/ \
      --header "x-api-key: YOUR_API_KEY" \
      --header "Content-Type: application/json" \
      --data '{"users": [42]}'
    ```
  </Step>
</Steps>

***

## Related

<CardGroup cols={2}>
  <Card title="Permissions flow" icon="key" href="/platform-api/permissions/overview">
    Granting to a group, on all three axes.
  </Card>

  <Card title="Onboarding flow" icon="user-plus" href="/platform-api/invitations/overview">
    Invite, group, and grant before somebody accepts.
  </Card>

  <Card title="Permission group object" icon="code" href="/platform-api/permission-groups/permission-group">
    Every field a group returns.
  </Card>

  <Card title="Groups in the app" icon="users" href="/workspace/groups">
    The same groups, managed by hand.
  </Card>
</CardGroup>