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

# Manage Dataset Restrictions with the API

> Restrict datasets, create user groups, sync their members, and grant access to restricted data with a Management Key and the Honeycomb API

EntBeta

> [!NOTE]
>
> Dataset restrictions are in public [beta](https://docs.honeycomb.io/troubleshoot/product-lifecycle/release-stages.md#beta) on the [Honeycomb Enterprise plan](https://www.honeycomb.io/pricing/).

This page is for Team Owners who want to automate dataset restrictions and user groups, for example to keep groups in sync with an identity provider.
To learn how restrictions work, visit [What are dataset restrictions?](https://docs.honeycomb.io/configure/teams/dataset-restrictions).

## Before you begin

The API uses a team-wide Management Key, so set one up with the scopes your automation needs.

* You must be a [Team Owner](https://docs.honeycomb.io/configure/teams/manage-permissions.md) to create a Management Key.
  To learn how, visit [Create Management API Key](https://docs.honeycomb.io/configure/teams/manage-api-keys.md#create-management-api-key).
* Send the key in an `Authorization: Bearer KEY_ID:SECRET` header.
  To learn more, visit [Authentication](https://docs.honeycomb.io/api/authentication.md).
* To restrict an environment, use the Honeycomb UI.
  The API restricts individual datasets.

The examples on this page use the US endpoint, `https://api.honeycomb.io`.
If your team is in the EU, use `https://api.eu1.honeycomb.io`.
They also assume that `HONEYCOMB_API_KEY` holds your key ID and secret, separated by a colon, and that `TEAM` holds your team slug.

### Scopes

Each task needs its own scope, so give a key only the scopes it uses.

| Task | Scopes |
| - | - |
| List datasets and find their IDs | `environments:read` |
| Restrict or unrestrict a dataset | `environments:write` |
| Unrestrict a dataset that a user group has access to | `environments:write` and `groups:write` |
| List user groups, their members, and their datasets | `groups:read` |
| Create, update, and delete user groups, and grant or revoke their access to datasets | `groups:write` |
| Add, remove, or replace group members | `groups:write` and `users:read` |
| List users and find their IDs | `users:read` |
| Filter users by group, or list each user's groups | `users:read` and `groups:read` |

A key with `environments:write`, `groups:write`, and `users:read` can do every task on this page.
A write scope includes its read scope.

> [!WARNING]
>
> A Management Key with the `groups:write` scope can grant any user group access to any individually restricted dataset on your team, including [restricted datasets](https://docs.honeycomb.io/configure/teams/dataset-restrictions).
> Honeycomb does not check whether the key can read those datasets.
> Give this scope only to keys that need to manage access, and store them as carefully as Team Owner credentials.

## Restrict a dataset and grant a group access

This walkthrough restricts a dataset and gives one person access to it through a user group.
Every request body uses the JSON:API format, so send `Content-Type: application/vnd.api+json` with each request that has a body.

1. Find the ID of the environment that holds the dataset.

   ```bash theme={}
   curl https://api.honeycomb.io/2/teams/$TEAM/environments \
     -H "Authorization: Bearer $HONEYCOMB_API_KEY"
   ```

   Each environment in the response has an `id`, such as `hcxen_01m7nbghdat0t6awx7gmnx1mck`.

2. Find the ID of the dataset, using its slug.

   ```bash theme={}
   curl "https://api.honeycomb.io/2/teams/$TEAM/environments/$ENVIRONMENT_ID/datasets?filter%5Bslug%5D=payments" \
     -H "Authorization: Bearer $HONEYCOMB_API_KEY"
   ```

   The dataset in the response has an `id`, such as `hcxds_01m7tkca520rdch211n2gq8d7t`, and a `restricted` attribute.

3. Restrict the dataset.

   ```bash theme={}
   curl -X PATCH https://api.honeycomb.io/2/teams/$TEAM/environments/$ENVIRONMENT_ID/datasets/$DATASET_ID \
     -H "Authorization: Bearer $HONEYCOMB_API_KEY" \
     -H "Content-Type: application/vnd.api+json" \
     -d '{
       "data": {
         "type": "datasets",
         "id": "'"$DATASET_ID"'",
         "attributes": { "restricted": true }
       }
     }'
   ```

   The response shows the dataset with `"restricted": true`.
   Only Team Owners can read the dataset until you grant a group access.

4. Create a user group.

   ```bash theme={}
   curl -X POST https://api.honeycomb.io/2/teams/$TEAM/groups \
     -H "Authorization: Bearer $HONEYCOMB_API_KEY" \
     -H "Content-Type: application/vnd.api+json" \
     -d '{
       "data": {
         "type": "groups",
         "attributes": {
           "name": "Payments team",
           "description": "Can read payments data"
         }
       }
     }'
   ```

   Honeycomb returns `201 Created` and the group's `id`, such as `hcxgr_01m7tkcmhh8kdamjrkhveeetxa`.
   Group names are unique in a team, so a duplicate name returns `422`.

5. Find the user's ID by email address.

   ```bash theme={}
   curl "https://api.honeycomb.io/2/teams/$TEAM/users?filter%5Bemail%5D=alex@example.com" \
     -H "Authorization: Bearer $HONEYCOMB_API_KEY"
   ```

   The user in the response has an `id`, such as `hcxus_01m7tkd0q3vfp8x2c9a4rjz6hn`, and their team `role`.

6. Add the user to the group.

   ```bash theme={}
   curl -X POST https://api.honeycomb.io/2/teams/$TEAM/groups/$GROUP_ID/relationships/members \
     -H "Authorization: Bearer $HONEYCOMB_API_KEY" \
     -H "Content-Type: application/vnd.api+json" \
     -d '{
       "data": [
         { "type": "users", "id": "'"$USER_ID"'" }
       ]
     }'
   ```

   Honeycomb returns `204 No Content`.

7. Grant the group access to the dataset.

   ```bash theme={}
   curl -X POST https://api.honeycomb.io/2/teams/$TEAM/groups/$GROUP_ID/relationships/datasets \
     -H "Authorization: Bearer $HONEYCOMB_API_KEY" \
     -H "Content-Type: application/vnd.api+json" \
     -d '{
       "data": [
         { "type": "datasets", "id": "'"$DATASET_ID"'" }
       ]
     }'
   ```

   Honeycomb returns `204 No Content`.
   You can grant access only to a restricted dataset, so an unrestricted dataset returns `422`.

Within a minute, the user can read the restricted dataset.
To revoke the group's access, send the same body with `DELETE`.

## Sync group membership

Use the members endpoints to keep a group in step with a list you manage elsewhere, such as a group in your identity provider.
Each request takes users by ID, so look up IDs first with the `users` endpoint.

| Method | Path | What it does |
| - | - | - |
| `POST` | `/2/teams/{team}/groups/{group}/relationships/members` | Adds the users in the request. |
| `DELETE` | `/2/teams/{team}/groups/{group}/relationships/members` | Removes the users in the request. |
| `PATCH` | `/2/teams/{team}/groups/{group}/relationships/members` | Replaces the group's members with the users in the request. |
| `GET` | `/2/teams/{team}/groups/{group}/relationships/members` | Lists the group's members. |

> [!WARNING]
>
> `PATCH` replaces the whole member list.
> Users who aren't in the request lose this group's access, and a request with an empty list removes every member.
> To change only some members, use `POST` or `DELETE`.

Within a minute, added users gain the group's access and removed users lose it, unless another group grants the same access.

## Remove a dataset's restriction

Remove a restriction when everyone on your team should read the dataset again.

```bash theme={}
curl -X PATCH https://api.honeycomb.io/2/teams/$TEAM/environments/$ENVIRONMENT_ID/datasets/$DATASET_ID \
  -H "Authorization: Bearer $HONEYCOMB_API_KEY" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "datasets",
      "id": "'"$DATASET_ID"'",
      "attributes": { "restricted": false }
    }
  }'
```

> [!WARNING]
>
> When you remove a dataset's restriction, Honeycomb removes the dataset from every user group that has access to it.
> If you restrict the dataset again later, grant groups access again.

If a user group has access to the dataset, the key also needs the `groups:write` scope.
Without it, Honeycomb returns `403` and the dataset stays restricted.

## Limits and errors

Plan your automation around these limits.

* A team can have up to 50 user groups.
* A members request can include up to 15,000 users.
* A request to grant or revoke datasets can include up to 100 datasets.
* Requests that add, remove, or replace members, or grant or revoke datasets, are all-or-nothing.
  If any user or dataset in the request is unknown, Honeycomb changes nothing and returns `422`, with one error for each unknown entry.
  Each error's `source.pointer` gives the entry's position in `data`, such as `/data/1`.
* If the `type` or `id` in a request body doesn't match the path, Honeycomb returns `409`.
* A request without `Content-Type: application/vnd.api+json` returns `415`.
* Requests count toward the API rate limits.
  To learn more, visit [Rate Limits](https://docs.honeycomb.io/api/rate-limit.md).

## Next steps

To continue configuring dataset restrictions, visit these pages:

* [Restrict Access to Datasets and Environments](https://docs.honeycomb.io/configure/teams/dataset-restrictions/restrict-access.md)
* [Manage User Groups](https://docs.honeycomb.io/configure/teams/dataset-restrictions/manage-user-groups.md)
* [Management Key Scopes](https://docs.honeycomb.io/configure/teams/manage-api-keys.md#management-key-scopes)
