Skip to main content
Ent Beta
Dataset restrictions are in public beta on the Honeycomb Enterprise plan.
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?.

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 to create a Management Key. To learn how, visit Create Management API Key.
  • Send the key in an Authorization: Bearer KEY_ID:SECRET header. To learn more, visit Authentication.
  • 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. A key with environments:write, groups:write, and users:read can do every task on this page. A write scope includes its read scope.
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. 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.
    Each environment in the response has an id, such as hcxen_01m7nbghdat0t6awx7gmnx1mck.
  2. Find the ID of the dataset, using its slug.
    The dataset in the response has an id, such as hcxds_01m7tkca520rdch211n2gq8d7t, and a restricted attribute.
  3. Restrict the dataset.
    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.
    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.
    The user in the response has an id, such as hcxus_01m7tkd0q3vfp8x2c9a4rjz6hn, and their team role.
  6. Add the user to the group.
    Honeycomb returns 204 No Content.
  7. Grant the group access to the dataset.
    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.
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.
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.

Next steps

To continue configuring dataset restrictions, visit these pages: