Skip to main content
Each Environment allows you to define API Keys for use within it.
You can create API Keys at the Environment level only. API Keys are shared and available for you to use across all Datasets in your Environment.
You can create and manage Environment-level API Keys through the Honeycomb UI. To create and manage Team-level resources, visit Team API Keys.

​
What are Environment-level API Keys?

In Honeycomb, some API keys are associated with Honeycomb Environments, which organize all of your Honeycomb resources and consist of a set of datasets, a set of API keys, a set of calculated fields, and a set of markers. When you create an API key, you assign it a set of permissions, which determines which actions your Team can use it to perform in the associated Environment. Any programmatic request sent to Honeycomb must use an API Key.

​
Uses

Honeycomb uses two types of Environment-level API keys, each for different purposes:
  • Ingest Keys: You can use these API Keys to send telemetry data to Honeycomb.
  • Configuration Keys: You can use these API Keys to manage resources in your Honeycomb Environment.
To learn more about using API Keys, visit Best Practices for API Keys.

​
Find API Keys

When you join Honeycomb, we help you create your first Team and Environment. As part of this process, we create your first Environment-level API Key—a Configuration Key—for you.
For security reasons, you can access the value of your 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 find your API Keys:
  1. Log in to the Honeycomb UI.
  2. Select the Environments selector in the navigation menu, then select Manage Environments.
  3. In the list, locate the Environment for which you would like to find API Keys, and select its name to view the available settings.
  4. Select the API Keys view.
  5. Select the view that corresponds to the type of API Keys that you would like to view, either Ingest or Configuration.
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 by Name, Description, or Key ID box.
Screenshot of the Ingest API keys list. Descriptions appear below key names, and one long description is cut off after two lines. The search box reads Search by Name, Description, or Key ID.

​
Create API Key

To create an API Key, you must be a Team Owner.
Whenever you create an Environment, we automatically create your first Configuration Key for you.
To create your API Key:
  1. Log in to the Honeycomb UI.
  2. Select the Environments selector in the navigation menu, then select Manage Environments.
  3. In the list, locate the Environment where you want to add an API Key, and select its name to view the available settings.
  4. Select the API Keys view.
  5. Select the view that corresponds to the type of API Key that you would like to create, either Ingest or Configuration.
  6. Select Create Ingest API Key or Create Configuration API Key.
  7. In the dialog, enter the details for your API Key:
    Screenshot of the Create ingest API key dialog. The optional Description field shows the placeholder text: e.g. Used by the checkout service in prod. Rotate in AWS Secrets Manager.
    For Ingest Keys, choose permissions carefully; they are permanent. To change permissions, you must delete the API Key and create a new one.
  8. Select Create.
  9. For Ingest Keys, copy your Key Secret and save it to a secure location, then select Done. Honeycomb returns it only upon creation, and you must copy or reveal it before you can select Done. Configuration Keys can be retrieved from the Honeycomb UI at any time.
    Store your API keys securely and never check them into version control systems, such as Git.
Your new API Key appears in the list of keys. The Key ID is a label that identifies this key in the Honeycomb UI. To learn how to use your new key, visit API Documentation: Authentication. To learn more about what you can do with your new key, visit Honeycomb API Documentation. Or send data to Honeycomb with an Ingest Key.

​
Change API Key

To modify an API Key, you must be a Team Owner.
To change your API Key:
  1. Log in to the Honeycomb UI.
  2. Select the Environments label on the top-left, then select Manage Environments.
  3. In the list, locate the Environment that contains the API Key that you want to edit, and select its name to view the available settings.
  4. Select the API Keys view.
  5. Select the view that corresponds to the type of API Key that you would like to change, either Ingest or Configuration.
  6. In the list, locate the API Key that you want to change, and select its Edit (pencil) icon. For Configuration Keys, Honeycomb opens a read-only view of the key; select Edit to change it.
  7. Change the API Key’s details as desired. To learn more about the actions that you can assign to API Keys, visit the API Key permissions section. To add, edit, or clear the key’s description, change the Description (optional) field. To clear the description, delete all of its text.
    Screenshot of the Edit API Key dialog for a Configuration Key. The Description field contains: Used by the checkout service in prod. Rotate in AWS Secrets Manager.
    For Ingest API keys, you cannot change the selected actions, but you can delete the API Key.
  8. Select Save.
Your API Key will be changed, but it may take several minutes for the changes to go into effect. Changing a key’s name or whether it is enabled does not change its description.

​
Describe API Keys

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, and returns it in API responses. 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. Only Team Owners can add, edit, or clear descriptions. Team members who are not Team Owners can read a key’s description in the list. They can also read it when they open an Ingest Key. Only Team Owners can open a Configuration Key, so other team members see at most the first two lines of its description.

​
Manage Descriptions with the API

You can set a key’s description with the Key Management API for Ingest and Configuration Keys. Send the description attribute, a string of up to 2,000 characters, to the Create an API Key and Update an API Key endpoints.
  • Responses from the Key Management API always include description. The value is an empty string if the key has no description.
  • To keep a key’s description unchanged when you update the key, omit description or send null.
  • To clear a key’s description, send an empty string ("").

​
Delete Ingest Keys

Deleting an Ingest Key is permanent, so make sure you really want to delete your Ingest Key before doing so.To delete an Ingest Key, you must be a Team Owner.
To delete your Ingest Key:
  1. Log in to the Honeycomb UI.
  2. Select the Environments label on the top-left, then select Manage Environments.
  3. In the list, locate the Environment that contains the API Key that you want to delete, and select its name to view the available settings.
  4. Select the API Keys view.
  5. Select the Ingest view.
  6. In the list, locate the Ingest Key that you want to delete, and select its Delete (trash) icon.
  7. In the Delete Ingest API Key? dialog, type the name of the Ingest Key, which appears above the field.
  8. Select Delete.
Your Ingest Key will no longer show in the list, but it may take several minutes for the process to complete.

​
Disable Configuration Keys

To disable a Configuration Key, you must be a Team Owner, and you must have at least one remaining Configuration Key in your Environment.
To disable your Configuration Key:
  1. Log in to the Honeycomb UI.
  2. Select the Environments label on the top-left, then select Manage Environments.
  3. In the list, locate the Environment that contains the API Key that you want to disable, and select its name to view the available settings.
  4. Select the API Keys view.
  5. Select the Configuration view.
  6. In the list, locate the Configuration Key that you want to disable, and select its Edit (pencil) icon, then select Edit.
  7. Turn off the Enabled toggle.
  8. Select Save.
Your Configuration Key remains in the list, and its Status changes to Disabled. It may take several minutes for the change to go into effect.

​
Enable Configuration Keys

To enable a Configuration Key, you must be a Team Owner.
To enable your Configuration Key:
  1. Log in to the Honeycomb UI.
  2. Select the Environments label on the top-left, then select Manage Environments.
  3. In the list, locate the Environment that contains the API Key that you want to enable, and select its name to view the available settings.
  4. Select the API Keys view.
  5. Select the Configuration view.
  6. In the list, locate the Configuration Key that you want to enable, and select its Edit (pencil) icon, then select Edit.
  7. Turn on the Enabled toggle.
  8. Select Save.
Your Configuration Key’s Status changes to Enabled. It may take several minutes for the change to go into effect.

​
API Key Permissions

Honeycomb uses two types of Environment-level API keys, each for different purposes:
  • Ingest Keys: Generally used to send telemetry data to Honeycomb.
  • Configuration Keys: Generally used to manage resources in your Honeycomb Environment.
However, you can manage the actions that API Keys may perform in your Environment at a more granular level.

​
Ingest Keys

Ingest Keys are Environment-level API Keys that you can use to send telemetry data to Honeycomb. Ingest Keys have a single permission available, Can create services/datasets, which controls whether they can implicitly create datasets. If an event is sent to Honeycomb specifying a non-existent dataset, Honeycomb will create a new dataset if the associated Ingest Key can implicitly create datasets.
You cannot change permissions assigned to an Ingest Key after you have created the key. You can delete the Ingest Key.
You can programmatically manage Ingest Keys by using our Key Management APIs.

​
Classic Ingest Keys

Ingest Keys are supported for Honeycomb Classic environments, provided the minimum required version of the software sending data in is in use. Please reference the table below to find the minimum supported version for your libraries, and upgrade, if necessary, prior to using Ingest Keys.

​
Configuration Keys

Configuration Keys are API Keys that you can use to manage resources in your Honeycomb Environments. Configuration Keys may have any number of these permissions:
Although you may use Configuration Keys to send telemetry data to Honeycomb, we recommend that you use Ingest Keys instead; they are built specifically for this purpose.

​
Troubleshoot

To see common issues when managing API Keys and their solutions, visit Common Issues with Configuring Honeycomb: API Keys.