Best Practices for API Keys

We recommend that you follow certain best practices when using API Keys.

​

Use API Key types appropriately

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

​

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

Check out:

• our guides on sending data to Honeycomb
• our API Documentation on creating events to learn more
• our documentation on finding your Ingest Key

​

Management Keys

Management API Keys allow you to manage API Keys and Environments at the Team level. Each key has a set of scopes, which can not be altered once the key has been created. Check out:

• our API Documentation to learn more about what you can do with a Management Key
• our documentation on finding your Management Key

​

Configuration Keys

Configuration API Keys allow you to manage resources in your Environment, such as Boards, Columns, Markers, Triggers, and SLOs. 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. Check out:

• our API Documentation to learn more about what you can do with a Configuration Key
• our documentation on finding your Configuration Key

​

Use different API keys for different purposes

For example, the API key used to send data in from your production cluster should be different from 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.

​

Describe each API key

Add a description to each API key that says where the key is used and how to rotate it. When a key must be rotated or revoked, your team can find the right service and the right steps without searching code or asking around. Good descriptions answer these questions:

• Which service, pipeline, or person uses the key?
• Where is the key stored?
• How do you rotate it, and who owns it?

For example:

• Used by the checkout service in prod. Rotate in AWS Secrets Manager.
• Used by the deploy pipeline to create markers. Rotate in the CI secrets store. Owned by the Platform team.

To add or change a description, visit Manage Environment API Keys for Ingest and Configuration Keys, or Manage Team API Keys for Management Keys.