The Honeycomb Environments API provides administrative capabilities for managing environments within a Honeycomb team. Environments allow organizations to separate telemetry data across different stages such as development, staging, and production. The API supports listing, creating, updating, and deleting environments, along with the Auth API for validating API keys and determining their associated team and environment permissions.
openapi: 3.1.0
info:
title: Honeycomb Environments API
description: >-
The Honeycomb Environments API provides administrative capabilities for
managing environments within a Honeycomb team. Environments allow
organizations to separate telemetry data across different stages such
as development, staging, and production. The API supports listing,
creating, updating, and deleting environments, along with the Auth API
for validating API keys and determining their associated team and
environment permissions. The Key Management API enables listing,
creating, updating, and deleting API keys for a team.
version: '1.0'
contact:
name: Honeycomb Support
url: https://support.honeycomb.io
termsOfService: https://www.honeycomb.io/terms-of-service
externalDocs:
description: Honeycomb Environments API Documentation
url: https://api-docs.honeycomb.io/api/environments
servers:
- url: https://api.honeycomb.io
description: Honeycomb Production API
tags:
- name: Auth
description: >-
Validate API key authentication and determine associated team and
environment permissions.
- name: Environments
description: >-
Manage environments within a Honeycomb team for separating telemetry data
across stages.
- name: Key Management
description: >-
Manage API keys for a team, including listing, creating, updating, and
deleting keys.
security:
- ApiKeyAuth: []
paths:
/1/environments:
get:
operationId: listEnvironments
summary: List all environments
description: >-
Returns a list of all environments within the team.
tags:
- Environments
responses:
'200':
description: A list of environments
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Environment'
'401':
description: Unauthorized
post:
operationId: createEnvironment
summary: Create an environment
description: >-
Creates a new environment for separating telemetry data across stages
such as development, staging, and production.
tags:
- Environments
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EnvironmentCreateRequest'
responses:
'201':
description: Environment created
content:
application/json:
schema:
$ref: '#/components/schemas/Environment'
'401':
description: Unauthorized
/1/environments/{environmentId}:
get:
operationId: getEnvironment
summary: Get an environment
description: >-
Returns a single environment by its ID.
tags:
- Environments
parameters:
- $ref: '#/components/parameters/environmentId'
responses:
'200':
description: Environment details
content:
application/json:
schema:
$ref: '#/components/schemas/Environment'
'401':
description: Unauthorized
'404':
description: Environment not found
put:
operationId: updateEnvironment
summary: Update an environment
description: >-
Updates an environment's name, description, or color.
tags:
- Environments
parameters:
- $ref: '#/components/parameters/environmentId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EnvironmentUpdateRequest'
responses:
'200':
description: Environment updated
content:
application/json:
schema:
$ref: '#/components/schemas/Environment'
'401':
description: Unauthorized
'404':
description: Environment not found
delete:
operationId: deleteEnvironment
summary: Delete an environment
description: >-
Deletes an environment.
tags:
- Environments
parameters:
- $ref: '#/components/parameters/environmentId'
responses:
'204':
description: Environment deleted
'401':
description: Unauthorized
'404':
description: Environment not found
/1/auth:
get:
operationId: getAuth
summary: Authenticate API key
description: >-
Validates authentication for a key and returns the team and environment
that the key belongs to.
tags:
- Auth
responses:
'200':
description: Successful authentication
content:
application/json:
schema:
$ref: '#/components/schemas/AuthInfo'
'401':
description: Unauthorized - invalid API key
/1/auth/permissions:
get:
operationId: listAuthorizations
summary: List authorizations
description: >-
Determines what authorizations have been granted to the API key.
tags:
- Auth
responses:
'200':
description: List of authorizations for the key
content:
application/json:
schema:
$ref: '#/components/schemas/AuthPermissions'
'401':
description: Unauthorized - invalid API key
/1/api_keys:
get:
operationId: listApiKeys
summary: List all API keys
description: >-
Returns a list of all API keys for the team.
tags:
- Key Management
responses:
'200':
description: A list of API keys
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ApiKey'
'401':
description: Unauthorized
post:
operationId: createApiKey
summary: Create an API key
description: >-
Creates a new API key for the team with specified permissions and
environment scope.
tags:
- Key Management
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ApiKeyCreateRequest'
responses:
'201':
description: API key created
content:
application/json:
schema:
$ref: '#/components/schemas/ApiKey'
'401':
description: Unauthorized
/1/api_keys/{keyId}:
get:
operationId: getApiKey
summary: Get an API key
description: >-
Returns a single API key by its ID.
tags:
- Key Management
parameters:
- $ref: '#/components/parameters/keyId'
responses:
'200':
description: API key details
content:
application/json:
schema:
$ref: '#/components/schemas/ApiKey'
'401':
description: Unauthorized
'404':
description: API key not found
put:
operationId: updateApiKey
summary: Update an API key
description: >-
Updates an API key's name, permissions, or disabled status.
tags:
- Key Management
parameters:
- $ref: '#/components/parameters/keyId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ApiKeyUpdateRequest'
responses:
'200':
description: API key updated
content:
application/json:
schema:
$ref: '#/components/schemas/ApiKey'
'401':
description: Unauthorized
'404':
description: API key not found
delete:
operationId: deleteApiKey
summary: Delete an API key
description: >-
Deletes an API key.
tags:
- Key Management
parameters:
- $ref: '#/components/parameters/keyId'
responses:
'204':
description: API key deleted
'401':
description: Unauthorized
'404':
description: API key not found
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-Honeycomb-Team
description: >-
Honeycomb Configuration API key with appropriate administrative
permissions.
parameters:
environmentId:
name: environmentId
in: path
required: true
description: >-
The unique identifier for the environment.
schema:
type: string
keyId:
name: keyId
in: path
required: true
description: >-
The unique identifier for the API key.
schema:
type: string
schemas:
Environment:
type: object
properties:
id:
type: string
description: >-
Unique identifier for the environment.
name:
type: string
description: >-
The display name of the environment.
slug:
type: string
description: >-
The URL-safe slug identifier for the environment.
description:
type: string
description: >-
A description of the environment.
color:
type: string
description: >-
A color associated with the environment for UI display.
created_at:
type: string
format: date-time
description: >-
ISO8601 formatted time the environment was created.
updated_at:
type: string
format: date-time
description: >-
ISO8601 formatted time the environment was last updated.
EnvironmentCreateRequest:
type: object
required:
- name
properties:
name:
type: string
description: >-
The display name for the environment.
description:
type: string
description: >-
An optional description for the environment.
color:
type: string
description: >-
An optional color for the environment.
EnvironmentUpdateRequest:
type: object
properties:
name:
type: string
description: >-
An updated display name for the environment.
description:
type: string
description: >-
An updated description for the environment.
color:
type: string
description: >-
An updated color for the environment.
AuthInfo:
type: object
properties:
team:
type: object
description: >-
The team associated with the API key.
properties:
slug:
type: string
description: >-
The slug identifier for the team.
name:
type: string
description: >-
The display name of the team.
environment:
type: object
description: >-
The environment associated with the API key, if applicable.
properties:
slug:
type: string
description: >-
The slug identifier for the environment.
name:
type: string
description: >-
The display name of the environment.
AuthPermissions:
type: object
properties:
api_key_access:
type: object
description: >-
The permissions and access levels granted to the API key.
additionalProperties:
type: boolean
ApiKey:
type: object
properties:
id:
type: string
description: >-
Unique identifier for the API key.
name:
type: string
description: >-
The display name of the API key.
type:
type: string
description: >-
The type of API key.
enum:
- configuration
- ingest
disabled:
type: boolean
description: >-
Whether the API key is disabled.
permissions:
type: object
description: >-
The permissions granted to this API key.
additionalProperties:
type: boolean
environment_id:
type: string
description: >-
The environment this key is scoped to, if applicable.
secret:
type: string
description: >-
The API key secret, only returned upon creation.
created_at:
type: string
format: date-time
description: >-
ISO8601 formatted time the API key was created.
ApiKeyCreateRequest:
type: object
required:
- name
- type
properties:
name:
type: string
description: >-
The display name for the API key.
type:
type: string
enum:
- configuration
- ingest
permissions:
type: object
description: >-
The permissions to grant to this API key.
additionalProperties:
type: boolean
environment_id:
type: string
description: >-
The environment to scope this key to.
ApiKeyUpdateRequest:
type: object
properties:
name:
type: string
description: >-
An updated display name for the API key.
disabled:
type: boolean
description: >-
Whether to disable the API key.
permissions:
type: object
description: >-
Updated permissions for the API key.
additionalProperties:
type: boolean