Working with API Keys (v2)

API Keys are team-scoped resources that control access to your Honeycomb data. This v2 API requires Management Key authentication.

Management Key Required

The API Keys API requires a Management Key (not a regular API key). See Authentication for setup.

Automatic Pagination

The list() and list_async() methods automatically paginate through all results. For teams with many API keys, this may result in multiple API requests. The default rate limit is 100 requests per minute per operation. If you need higher limits, contact Honeycomb support.

Key Types

• Ingest Keys: For sending data to Honeycomb (used in instrumentation)
• Configuration Keys: For API access (querying, managing resources)

Basic API Key Operations

List API Keys

async def list_api_keys(client: HoneycombClient) -> list[ApiKey]:
    """List all API keys in the authenticated team.

    Args:
        client: HoneycombClient with management key

    Returns:
        List of API keys
    """
    keys = await client.api_keys.list_async()
    for key in keys:
        disabled = " (disabled)" if key.disabled else ""
        print(f"{key.name} ({key.key_type}){disabled}: {key.id}")
    return keys


_by_type
async def list_ingest_keys(client: HoneycombClient) -> list[ApiKey]:
    """List only ingest keys.

    Args:
        client: HoneycombClient with management key

    Returns:
        List of ingest API keys
    """
    keys = await client.api_keys.list_async(key_type="ingest")
    print(f"Found {len(keys)} ingest keys")
    return keys

Filter by Key Type

async def list_ingest_keys(client: HoneycombClient) -> list[ApiKey]:
    """List only ingest keys.

    Args:
        client: HoneycombClient with management key

    Returns:
        List of ingest API keys
    """
    keys = await client.api_keys.list_async(key_type="ingest")
    print(f"Found {len(keys)} ingest keys")
    return keys

Get a Specific API Key

async def get_api_key(client: HoneycombClient, key_id: str) -> ApiKey:
    """Get a specific API key by ID.

    Args:
        client: HoneycombClient with management key
        key_id: API key ID

    Returns:
        The API key object
    """
    key = await client.api_keys.get_async(key_id)
    print(f"Name: {key.name}")
    print(f"Type: {key.key_type}")
    print(f"Environment: {key.environment_id}")
    print(f"Disabled: {key.disabled}")
    if key.permissions:
        perms_dict = key.permissions.model_dump() if hasattr(key.permissions, "model_dump") else key.permissions
        print(f"Permissions: {[k for k, v in perms_dict.items() if v]}")
    return key

Create an API Key

async def create_api_key(client: HoneycombClient, environment_id: str) -> tuple[str, str]:
    """Create a new configuration API key with full permissions.

    Args:
        client: HoneycombClient with management key
        environment_id: Environment ID for the key

    Returns:
        Tuple of (key_id, secret)

    Note: The secret is only returned during creation. Save it securely!
    """
    key = await client.api_keys.create_async(
        api_key=ConfigurationKey(
            key_type="configuration",
            name="Integration Test Key",
            permissions={
                "create_datasets": True,
                "send_events": True,
                "manage_markers": True,
                "manage_triggers": True,
                "manage_boards": True,
                "run_queries": True,
                "manage_columns": True,
                "manage_slos": True,
                "manage_recipients": True,
                "manage_privateBoards": True,
            },
        ),
        environment_id=environment_id,
    )

    # Secret is only available during creation!
    print(f"Created key: {key.id}")
    print(f"Secret: {key.attributes.secret}")
    print("⚠️  Save the secret - it won't be shown again!")

    return key.id, key.attributes.secret

Update an API Key

async def update_api_key(client: HoneycombClient, key_id: str) -> ApiKey:
    """Update an API key's name and status.

    Args:
        client: HoneycombClient with management key
        key_id: API key ID to update

    Returns:
        The updated API key
    """
    # Update with new values using convenience parameters
    updated = await client.api_keys.update_async(
        key_id=key_id,
        name="Updated Integration Test Key",
        disabled=True,  # Disable the key
    )
    return updated

Delete an API Key

async def delete_api_key(client: HoneycombClient, key_id: str) -> None:
    """Delete an API key.

    Args:
        client: HoneycombClient with management key
        key_id: API key ID to delete

    Warning: Deleting a key immediately revokes access. Applications using
    this key will fail to authenticate.
    """
    await client.api_keys.delete_async(key_id=key_id)

Key ID Prefixes

Key IDs have prefixes indicating their type: - hcxik_... - Ingest Key - hcxlk_... - Configuration Key

Sync Usage

All API key operations have sync equivalents (team is auto-detected):

with HoneycombClient(
    management_key="hcamk_xxx",
    management_secret="xxx",
    sync=True
) as client:
    keys = client.api_keys.list()
    key = client.api_keys.get(key_id)
    key = client.api_keys.create(ApiKeyCreate(...))
    updated = client.api_keys.update(key_id, ApiKeyUpdate(...))
    client.api_keys.delete(key_id)

Configuration Key Permissions

When creating configuration keys, you MUST specify permissions. Without them, the key will have NO permissions:

from honeycomb.models.api_keys import ApiKeyCreate, ApiKeyType

# Full access configuration key
key = await client.api_keys.create_async(
    api_key=ApiKeyCreate(
        name="Full Access Key",
        key_type=ApiKeyType.CONFIGURATION,
        environment_id="hcaen_xxx",
        permissions={
            "create_datasets": True,
            "send_events": True,
            "manage_markers": True,
            "manage_triggers": True,
            "manage_boards": True,
            "run_queries": True,
            "manage_columns": True,
            "manage_slos": True,
            "manage_recipients": True,
            "manage_privateBoards": True,
        }
    )
)

Available permissions: - create_datasets - Create and manage datasets - send_events - Send events to datasets - manage_markers - Create and manage markers - manage_triggers - Create and manage triggers - manage_boards - Create and manage boards - run_queries - Execute queries - manage_columns - Manage columns - manage_slos - Create and manage SLOs - manage_recipients - Manage recipients - manage_privateBoards - Manage private boards

Important: The secret field is only returned when creating a key. Save it immediately - it cannot be retrieved later!