Understanding API Keys | Honeycomb

Understanding API Keys

Any programmatic request sent to Honeycomb must use an API Key. API Keys can be used for a number of different purposes.

Use specialized Ingest Keys to send telemetry data to Honeycomb, and use Configuration Keys to manage many of the resources in your Environment. API keys are set at the Environment level, and apply to all datasets in the Environment.

Note
Ingest Key support for Honeycomb Classic is under development. Please continue to use Configuration Keys until Ingest Keys are available for Classic Teams.

Find API Keys 

Locate your Environment’s API Keys:

  1. In the left navigation bar under the Honeycomb logo, select the Environments banner. A menu appears with Manage Environments and a list of existing Environments.

    Display of the Honeycomb UI with the selected Environments banner and resulting Environments menu displayed
  2. Select Manage Environments. The next screen displays a list of Environments and details about each Environment.

    Display of Environments page with Name and API Keys columns, and example Environments
  1. In the row of the target Environment, select View API Keys. The next screen lists the API Keys associated with the Environment. Copy the key value in this screen by selecting the copy icon adjacent to the key value.

Manage API Keys 

API keys are managed at the Environment level and found in your Environment Settings. API keys are created and managed only via the UI. You must be a Team Owner to create and manage API keys.

Note
Honeycomb Classic API keys are scoped to all dataset(s) and data in the Classic section. API keys can be created, modified, or disabled only via the UI. Learn more about Honeycomb versus Honeycomb Classic.

Ingest Keys 

We recommend using Ingest API Keys to send data to Honeycomb. They are specialized, environment-scoped keys, which are designed to securely transmit telemetry data, including the optional creation of new datasets. They have the following properties:

  • Limited permissions: Can only be used to write telemetry data, and optionally create new datasets.
  • Immutable: Once created, their permissions cannot be altered, which makes them the safest option for client-side instrumentation.
  • Can be deleted: These keys can be temporarily disabled or permanently deleted, which help users manage clutter and adhere to certain compliance standards.

The full Ingest Key will only be available during creation. If the full, 64-character key is misplaced, we recommend disabling or deleting the key, and creating a new one. Once created, only the first 32 characters of the key will be visible in the UI. This 32 character string consists of a region-specific prefix and the key’s identifier (ID), and is considered non-sensitive.

Use the Details modal to update the Ingest Key’s name, its enabled state, or to delete it completely.

Screenshot of the Ingest Key details modal
Note
Ingest Key support for Honeycomb Classic is under development.

Configuration Keys 

Configuration API Keys allow you to manage resources such as Boards, Columns, Markers, Triggers, and SLOs in your environment. Their permissions can be modified after their creation, and while they can be granted the permission to send events it is recommended that Ingest API Keys be used for that purpose.

Use the Edit API Key modal to modify the Configuration API Key’s name, its visibility to team members, its enabled state, and its permissions.

Screenshot of the Edit API Key modal with several permissions enabled

API Key Permissions 

Ingest Keys 

An Ingest API Key can currently only have a single permission controlling implicit dataset creation. 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.

Note

Ingest Key permissions cannot be modified after the key has been created.

Ingest Key support for Honeycomb Classic is under development.

Configuration Keys 

A Configuration API Key can have any number of the following permissions:

API Key Permission Auth API value Description
Send Events send events Send events to Honeycomb. Used as the API Key for getting data in 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.
Note

Configuration API Keys may be used to send telemetry to Honeycomb, but we recommend using Ingest Keys as they are built specifically for this purpose.

Ingest Key support for Honeycomb Classic is under development.

Best Practices for API Keys 

We recommend using Ingest Keys to send data to Honeycomb, and Configuration keys to manage your Honeycomb resources.

You should use different API keys for different purposes. For example, the API key used to send data in from your production cluster should be different then the API key used for testing; the key used by your build process to create markers should be different from either of those.

Separating these purposes among different API keys allows you to revoke permissions on one key without affecting the abilities of others. It also minimizes the negative effects if a key leaks or is lost.

Note
Ingest Key support for Honeycomb Classic is under development.