Honeycomb User Management API Guide

Auth method: API Key (X-Honeycomb-Team header)

Setup steps

1. Log in to Honeycomb and navigate to Team Settings.
2. Under 'API Keys', create a Configuration API key (not an Ingest key) - Configuration keys are required for management operations.
3. Copy the key value; it is shown only once.
4. Pass the key in the X-Honeycomb-Team HTTP header on every request.

Required scopes

List Team Members

• Method: GET
• URL: https://api.honeycomb.io/1/team_memberships
• Watch out for: Requires a Configuration API key. Ingest keys return 401.

Request example

GET /1/team_memberships HTTP/1.1
Host: api.honeycomb.io
X-Honeycomb-Team: YOUR_CONFIG_API_KEY

Response example

[
  {
    "id": "abc123",
    "email": "user@example.com",
    "name": "Jane Doe",
    "role": "member",
    "created_at": "2024-01-15T10:00:00Z"
  }
]

Invite Team Member

• Method: POST
• URL: https://api.honeycomb.io/1/team_memberships
• Watch out for: Sends an email invitation; the user must accept before they appear as an active member.

Request example

POST /1/team_memberships HTTP/1.1
Host: api.honeycomb.io
X-Honeycomb-Team: YOUR_CONFIG_API_KEY
Content-Type: application/json

{"email":"newuser@example.com","role":"member"}

Response example

{
  "id": "def456",
  "email": "newuser@example.com",
  "role": "member",
  "created_at": "2025-01-20T12:00:00Z"
}

Update Team Member Role

• Method: PUT
• URL: https://api.honeycomb.io/1/team_memberships/{id}
• Watch out for: Only 'role' is updatable via this endpoint. Email and name cannot be changed through the API.

Request example

PUT /1/team_memberships/def456 HTTP/1.1
Host: api.honeycomb.io
X-Honeycomb-Team: YOUR_CONFIG_API_KEY
Content-Type: application/json

{"role":"admin"}

Response example

{
  "id": "def456",
  "email": "newuser@example.com",
  "role": "admin"
}

Remove Team Member

• Method: DELETE
• URL: https://api.honeycomb.io/1/team_memberships/{id}
• Watch out for: Immediately removes the member. There is no soft-delete or deactivation state.

Request example

DELETE /1/team_memberships/def456 HTTP/1.1
Host: api.honeycomb.io
X-Honeycomb-Team: YOUR_CONFIG_API_KEY

Response example

HTTP/1.1 204 No Content

• Rate limits: Honeycomb's public documentation does not publish explicit numeric rate limits for the management API. Rate-limit behavior is enforced server-side; the docs do not specify response headers or Retry-After semantics for management endpoints.

• Rate-limit headers: No

• Retry-After header: No

• Rate-limit notes: No documented per-plan rate-limit tiers for the management API as of the policy date. Treat HTTP 429 responses as signals to back off.

• Pagination method: none

• Default page size: 0

• Max page size: 0

• Pagination pointer: Not documented

• Webhooks available: No

• Webhook notes: Honeycomb does not document webhooks for user-management or team-membership events.

• Alternative event strategy: Poll GET /1/team_memberships on a schedule to detect membership changes.

• SCIM available: No
• SCIM version: Not documented
• Plan required: N/A
• Endpoint: Not documented

Limitations:

• Honeycomb does not offer a native SCIM 2.0 endpoint as of the policy date.
• Automated provisioning must be handled via the REST management API or manual IdP-side workflows.

Three primary automation scenarios are supported by the current API surface:

Onboarding: POST to /1/team_memberships with email and role.

The invite triggers an email;

the member does not appear active in the identity graph until they accept.

Poll GET /1/team_memberships to confirm activation before downstream provisioning steps depend on membership state.

Role promotion: GET the member's id, then PUT /1/team_memberships/{id} with {"role":"admin"}.

Only role is mutable via PUT;

email and name fields are read-only through the API.

Offboarding: GET to resolve id by email, then DELETE /1/team_memberships/{id} for an immediate, hard removal - no soft-delete or deactivation state exists.

API key revocation for keys created by the removed user has no documented API endpoint;

that step must be completed manually in the Honeycomb UI, which is a gap in any fully automated offboarding pipeline.

Onboard a new engineer to the team

1. Obtain a Configuration API key from Team Settings.
2. POST to /1/team_memberships with the engineer's email and desired role ('member' or 'admin').
3. Confirm the engineer receives and accepts the invitation email.
4. GET /1/team_memberships to verify the new member appears with the correct role.

Watch out for: The member will not appear as active until they accept the invitation; poll the list endpoint to confirm.

Promote a member to admin

1. GET /1/team_memberships to retrieve the target member's id.
2. PUT /1/team_memberships/{id} with body {"role":"admin"}.
3. Verify the response returns the updated role.

Watch out for: Only the 'role' field is mutable via PUT; attempting to change email will be ignored or error.

Offboard a departing employee

1. GET /1/team_memberships to find the member's id by email.
2. DELETE /1/team_memberships/{id} to remove them immediately.
3. Rotate or revoke any API keys the user may have created (done via Team Settings UI; no documented API for key revocation by user).

Watch out for: API key revocation for keys created by the removed user must be handled manually in the Honeycomb UI; there is no documented API endpoint to list or revoke keys by user identity.

The most common integration trap is key type confusion: Configuration keys and Ingest keys are issued from the same UI but have entirely different permission scopes. Using an Ingest key against management endpoints silently fails with 401, which can be misread as an auth configuration error rather than a key-type mismatch.

A second structural caveat applies to identity graph completeness: because Honeycomb has no SCIM endpoint and no webhook events for membership changes, the only reliable way to keep an external identity graph in sync is scheduled polling of GET /1/team_memberships per team.

There is no push-based notification when a user accepts an invitation, changes roles, or is removed out-of-band via the UI.

Finally, the per-team API key model means a Configuration key is scoped to one team. Automations that span multiple teams must manage a separate key (and separate API calls) per team, which adds credential surface area and complicates secret rotation at scale.