Manage Environment-level API Keys

Each Environment allows you to define API Keys for use within it.

Tip
You can create custom fields 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, refer to Team-level Management 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 custom 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.

Warning
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 label on the top-left, 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.

Create API Key 

Important
To create an API Key, you must be a Team Owner.
Tip
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 label on the top-left, then select Manage Environments.

  3. In the list, locate the Environment to which you would like 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 API Key.

  7. In the Create API Key modal, enter a Name for the API Key, and select the actions you would like the API Key to be able to perform.

    To learn more about the actions that you can assign to API Keys, visit the API Key permissions section.

    Warning
    For Ingest API keys, you cannot change the selected permissions after saving, but you can delete the API Key.

    If you are creating a Configuration API Key, also select whether you would like the API Key to be visible to Team owners only or to all Team members.

  8. Select Save.

  9. If you have created an Ingest Key, copy your API Key and save it to a secure location. For security reasons, you will not be able to see the key again as the key is a concatenation of the key ID and secret.

    Warning
    For production deployments, you should store your API key securely and never check them into source control management systems, such as Git.
  10. Select Ok, I’ve copied the key

Your new API Key should now show in the list of keys.

Next steps 

Check out our API Documentation to learn more about what you can do with a Configuration Key, or look into sending data to Honeycomb with your new Ingest Key.

Change API Key 

Important
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 Details to view its settings.

  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.

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

Delete Ingest Keys 

Warning

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 Keys view.

  6. In the list, locate the Ingest Key that you want to delete, and select Details to view its settings.

  7. Select Delete.

  8. In the Delete Ingest API Key? modal, enter the unique identifier of the Ingest Key (located above the field).

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

Important
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 Keys view.

  6. In the list, locate the Configuration Key that you want to disable, and select Details to view its settings.

  7. Locate the Enable checkbox, and deselect it.

  8. Select Save.

Your Configuration Key will no longer show in the list, but it may take several minutes for the process to complete.

Enable Configuration Keys 

Important
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 Keys view.

  6. Select Show disabled keys.

  7. In the list, locate the Configuration Key that you want to enable, and select Details to view its settings.

  8. Locate the Enable checkbox, and select it.

  9. Select Save.

Your Configuration Key will show in the list of Configuration Keys, but it may take several minutes for the process to complete.

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

Note
You cannot change permissions assigned to 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.

Library Minimum Version
beeline-go 1.15.0
beeline-java 2.2.0
beeline-nodejs 4.1.0
beeline-python 3.6.0
beeline-ruby 3.1.0
buildevents 0.16.0
honeycomb-opentelemetry-dotnet 1.5.0
honeycomb-opentelemetry-go 0.10.0
honeycomb-opentelemetry-java 1.6.0
honeycomb-opentelemetry-node 0.7.0
honeycomb-opentelemetry-python 0.4.0b0
honeycomb-opentelemetry-web 0.0.4
libhoney-dotnet 1.4.0
libhoney-go 1.22.0
libhoney-java 1.6.0
libhoney-js 4.2.0
libhoney-py 2.4.0
libhoney-rb 2.3.0
husky 0.26.0
refinery 2.5.0

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:

Tip
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.
API Key Permission Auth API value Description
Send Events send events Send events to Honeycomb. Used as the API Key for sending data and for the Events API.
Create Datasets create datasets Create and manage datasets via API. Datasets may also be created implicitly; if an event is sent to Honeycomb specifying a non-existent dataset, an event using an API key with this permission will create a new dataset.
Manage Queries and Columns queries and columns Create and manage queries, columns, derived columns, and query annotations.
Run Queries run queries Execute existing queries using the Query Data API. This feature is available as part of the Honeycomb Enterprise plan.
Manage Public Boards boards Create and manage Boards.
Manage SLOs SLOs Create and manage SLOs and their Burn Alerts. SLO Management is available as part of the Honeycomb Pro and Enterprise plans. SLO Reporting is only available on the Honeycomb Enterprise plan.
Manage Triggers triggers Create and manage Triggers.
Manage Recipients recipients Create and manage Recipients.
Manage Markers markers Create and manage Markers.

Troubleshoot 

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