Create and manage Team-level Management API keys to control API keys across all Environments in your Team and set the scopes each key can access.
Management API Keys allow you to manage API Keys at the Team level, which includes all API Keys for the Environments associated with your team.Create and manage these team-scoped Management API Keys through the Honeycomb UI.
We require you to manually create a Management API Key.
When you create a Management API Key, you assign it a set of scopes, which determine what actions the API Key can perform in the associated Team.Use Management API Keys to authorize the Key Management API.
Refer to the Key Management API documentation for details.Any programmatic request sent to Honeycomb must use an API Key, but most Honeycomb APIs operate at the Environment level and require a Configuration Key for resource management.
To learn more about using API Keys, visit Best Practices for API Keys.
Find Management API Keys
To find your existing Management API Keys:
Log in to the Honeycomb UI.
From the navigation menu, select Account, and then Team Settings.
Select the API Keys view.
Each key’s description, if it has one, appears below the key’s name in smaller text.
The list shows up to two lines of the description; open the key to read all of it.
To find a key, enter part of its name, description, or Key ID in the search box.
Create Management API Key
To create a Management API Key, you must be a Team Owner.
For security reasons, you can access the secret portion of your Management API Key only while creating it.
You may be able to use the information you retrieve in this section to identify a key or its settings, so you can retrieve it from the safe location in which you previously stored it.
To create your API Key:
Log in to the Honeycomb UI.
From the navigation menu, select Account, and then Team Settings.
Select the API Keys view.
Select Create Management API Key.
In the Create management API key dialog, enter the details for your API Key:
Field
Description
API key name
Label for the API Key. Used to identify this key in the Honeycomb UI.
Description (optional)
Notes on where this key is used or how to rotate it. Do not include secrets. See Describe Management Keys.
Permissions
Actions this key is allowed to perform on Honeycomb resources. For each resource, select No access, Read-only, or Read and write. Users offers only No access and Read-only. For a full list of available scopes, visit Management Key Scopes.
Choose permissions carefully; they are permanent. To change them, you must delete the API Key and create a new one.
Select Create.
Copy your Key Secret and save it to a secure location.
Honeycomb returns it only upon creation.
Store your API keys securely and never check them into version control systems, such as Git.
Select Done.
Optionally, copy your Key ID.
You will need both your Key ID and Key Secret to authenticate requests to the API.
Your Key ID is always available after creation, but your Key Secret is not.
A description is an optional note about a key, such as where it is used or how to rotate it.
For example: Used by the checkout service in prod. Rotate in AWS Secrets Manager.
Descriptions help your team identify a key without searching code to find where it is used.
To learn how descriptions fit into key management, visit Best Practices for API Keys.
A description is not secret.
Honeycomb shows it wherever it shows the key’s name, to anyone who can see the key.
Do not put API keys, tokens, passwords, or other secrets in a description.
A description can contain up to 2,000 characters.
The Description (optional) field stops accepting input at that limit.
To add, edit, or clear a description, you must be a Team Owner.
Team members who are not Team Owners can read a key’s description in the list and when they open the key.
To add, edit, or clear the description of a Management Key:
Log in to the Honeycomb UI.
From the navigation menu, select Account, and then Team Settings.
Select the API Keys view.
In the list, locate the Management Key that you want to change, and select its Edit (pencil) icon.
In the Description (optional) field, enter the new description.
To clear the description, delete all of its text.
Select Save.
Changing a key’s name or whether it is enabled does not change its description.The Key Management API does not manage Management Keys, so you can set their descriptions only in the Honeycomb UI.
Disable Management Keys
To disable a Management Key, you must be a Team Owner.
To disable your Management Key:
Log in to the Honeycomb UI.
From the navigation menu, select Account, and then Team Settings.
Select the API Keys view.
In the list, locate the Management Key that you want to disable, and select its Edit (pencil) icon.
Turn off the Enabled toggle.
Select Save.
Your Management Key remains in the list, and its Status changes to Disabled.
It may take several minutes for the change to go into effect.
Delete Management Keys
Management Key deletion is permanent, so make sure you really want to delete your Management Key before doing so.To delete a Management Key, you must be a Team Owner.
To delete your Management Key:
Log in to the Honeycomb UI.
From the navigation menu, select Account, and then Team Settings.
Select the API Keys view.
In the list, locate the Management Key that you want to delete, and select its Delete (trash) icon.
In the Delete management API key? dialog, type the name of the Management Key, which appears above the field.
Select Delete.
Your Management Key will no longer appear in the list, but it may take several minutes for the process to complete.
Management Key Scopes
You can control the actions that a Management API Key may perform in your Team at a more granular level.
You cannot change scopes assigned to a Management Key after the key has been created.
Management Keys can be deleted.
Scope
Description
api-keys:read
Grants list and view details to the team’s API Keys.
api-keys:write
Grants create, list, update, delete and view details for the team’s API Keys.
environments:read
Grants list and view details to the team’s Environments and their datasets.
Grants list and view details for the team’s user groups, their members, and the datasets granted to them individually. Environment-wide access isn’t listed.
groups:write
Grants create, update, and delete for the team’s user groups, and lets the key add and remove group members and grant and revoke group access to datasets. Adding, removing, or replacing members also requires users:read.
users:read
Grants list for the team’s users, including each user’s role. With groups:read, the response also includes each user’s user groups.
mcp:read
Grants read access through Honeycomb MCP to Boards, Environments, SLOs, Triggers, service maps, Recipients, queries, Markers, Canvas investigations, anomaly detection signals, and Findings.
mcp:write
Grants everything mcp:read grants, plus write access to Boards, SLOs, Triggers, Recipients, Canvas investigations, Markers, anomaly detection signals, and Findings, when the key is used with Honeycomb MCP.
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.