Create, list, rotate, and revoke Honeycomb API keys (ingest, configuration, and management scopes) at the team level. Uses the v2 JSON:API surface (application/vnd.api+json) under /2/teams/{teamSlug}/api-keys. Requires a Management Key.
openapi: 3.1.0
info:
title: Honeycomb Key Management API
version: 1.0.0
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
contact:
email: support@honeycomb.io
description: 'The API allows programmatic management of many resources within Honeycomb.
Please report any discrepancies with actual API behavior in <a href="https://docs.honeycomb.io/troubleshoot/community/">Pollinators Slack</a> or to <a href="https://support.honeycomb.io/">Honeycomb
Support</a>.
'
externalDocs:
url: https://docs.honeycomb.io
servers:
- url: https://api.honeycomb.io
- url: https://api.eu1.honeycomb.io
tags:
- name: Key Management
description: "This API allows you to list, create, update, and delete API Keys for a Team.\n\n\nLearn more about [API keys here](https://docs.honeycomb.io/configure/environments/manage-api-keys/).\n\n\
## Authorization\n\n This API requires a Management Key passed via the HTTP Authorization header. Join the key ID and secret with a colon, like this: `Authorization: Bearer <key ID>:<secret>`.\n"
paths:
/2/teams/{teamSlug}/api-keys:
parameters:
- $ref: '#/components/parameters/teamSlug'
get:
security:
- bearerAuth:
- api-keys:read
tags:
- Key Management
summary: List all API Keys
description: 'List all API Keys for a Team.
'
operationId: listApiKeys
parameters:
- $ref: '#/components/parameters/PaginationCursor'
- $ref: '#/components/parameters/PaginationSize'
- name: filter[type]
in: query
schema:
type: string
enum:
- configuration
- ingest
description: "Specifies the type of API key to return. This parameter accepts the following values:\n - `ingest`: Returns only ingest API keys.\n - `configuration`: Returns only configuration\
\ API keys.\n\nThe endpoint will default to fetching all API keys regardless of type if this filter is omitted.\n"
required: false
responses:
'200':
description: Success
headers:
Ratelimit:
$ref: '#/components/headers/RateLimit'
RateLimitPolicy:
$ref: '#/components/headers/RateLimitPolicy'
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/ApiKeyListResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'422':
$ref: '#/components/responses/ValidationFailed'
'429':
$ref: '#/components/responses/RateLimited'
'500':
$ref: '#/components/responses/InternalError'
post:
security:
- bearerAuth:
- api-keys:write
tags:
- Key Management
summary: Create an API Key
description: 'This creates an API Key, which will return the API Key components in the response. The Key ID will be found at `data.id` and
the Key Secret will be found at `data.attributes.secret`. For security reasons the Key Secret will only be available during creation so make sure to save it.
To use a newly-created Ingest Key it should be passed in the `X-Honeycomb-Team` header with the API Key''s ID and secret
concatenated (and with no separator). For example, `X-Honeycomb-Team: hcxik_1234567890123456789012345612345678901234567890123456789012`
Check out our [best practices for API Keys](https://docs.honeycomb.io/get-started/best-practices/api-keys/#ingest-keys).
'
operationId: createApiKey
requestBody:
required: true
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/ApiKeyCreateRequest'
responses:
'201':
description: Created
headers:
Ratelimit:
$ref: '#/components/headers/RateLimit'
RateLimitPolicy:
$ref: '#/components/headers/RateLimitPolicy'
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/ApiKeyCreateResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'413':
$ref: '#/components/responses/PayloadTooLarge'
'415':
$ref: '#/components/responses/UnsupportedMediaType'
'422':
$ref: '#/components/responses/ValidationFailed'
'429':
$ref: '#/components/responses/RateLimited'
'500':
$ref: '#/components/responses/InternalError'
/2/teams/{teamSlug}/api-keys/{ID}:
parameters:
- $ref: '#/components/parameters/teamSlug'
- $ref: '#/components/parameters/ID'
get:
security:
- bearerAuth:
- api-keys:read
tags:
- Key Management
summary: Get an API Key
description: 'Fetches an environment API Key, either a key of type `ingest` or type `configuration` based on the
ID given.
'
operationId: getApiKey
responses:
'200':
description: Success
headers:
Ratelimit:
$ref: '#/components/headers/RateLimit'
RateLimitPolicy:
$ref: '#/components/headers/RateLimitPolicy'
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/ApiKeyResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/RateLimited'
'500':
$ref: '#/components/responses/InternalError'
patch:
security:
- bearerAuth:
- api-keys:write
tags:
- Key Management
summary: Update an API Key
description: 'Updates an API Key. The expected attributes depend on the key type:
- **Ingest Keys** (prefix `hcxik_`): Support `name` and `enabled` attributes
- **Configuration Keys** (prefix `hcxlk_`): Support `name`, `enabled`, and `permissions` attributes
'
operationId: updateApiKey
requestBody:
required: true
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/ApiKeyUpdateRequest'
examples:
ingestKey:
summary: Update an Ingest Key
value:
data:
id: hcxik_12345678901234567890123456
type: api-keys
attributes:
name: updated name
disabled: false
configurationKey:
summary: Update a Configuration Key
value:
data:
id: hcxlk_12345678901234567890123456
type: api-keys
attributes:
name: updated name
disabled: false
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: false
read_service_maps: true
visible_team_members: true
responses:
'200':
description: Success
headers:
Ratelimit:
$ref: '#/components/headers/RateLimit'
RateLimitPolicy:
$ref: '#/components/headers/RateLimitPolicy'
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/ApiKeyResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'413':
$ref: '#/components/responses/PayloadTooLarge'
'415':
$ref: '#/components/responses/UnsupportedMediaType'
'422':
$ref: '#/components/responses/ValidationFailed'
'429':
$ref: '#/components/responses/RateLimited'
'500':
$ref: '#/components/responses/InternalError'
delete:
security:
- bearerAuth:
- api-keys:write
tags:
- Key Management
summary: Delete an API Key
description: 'This deletes and immediately deactivates the API Key. This is an irreversible operation.
'
operationId: deleteApiKey
responses:
'204':
description: No Content
headers:
Ratelimit:
$ref: '#/components/headers/RateLimit'
RateLimitPolicy:
$ref: '#/components/headers/RateLimitPolicy'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/RateLimited'
'500':
$ref: '#/components/responses/InternalError'
components:
schemas:
ConfigurationKeyRequest:
type: object
title: Configuration Key
required:
- id
- type
- attributes
properties:
id:
type: string
pattern: ^hcxlk_[a-zA-Z0-9]{26}$
description: The unique identifier of the Configuration Key ID with hcxlk_ prefix
example: hcxlk_12345678901234567890123456
type:
type: string
enum:
- api-keys
attributes:
type: object
properties:
name:
type: string
description: A human-readable name for the API Key
example: updated key name
disabled:
type: boolean
description: Whether the API Key is enabled
example: false
permissions:
type: object
description: The permissions granted to this Configuration API Key. Values omitted will not be replaced.
properties:
create_datasets:
type: boolean
description: Whether this API Key can create new Datasets
send_events:
type: boolean
description: Whether this API Key can send Events
manage_markers:
type: boolean
description: Whether this API Key can manage Markers
manage_triggers:
type: boolean
description: Whether this API Key can manage Triggers
manage_boards:
type: boolean
description: Whether this API Key can manage Boards
run_queries:
type: boolean
description: Whether this API Key can run Queries
manage_columns:
type: boolean
description: Whether this API Key can manage Columns and Queries
manage_slos:
type: boolean
description: Whether this API Key can manage SLOs
manage_recipients:
type: boolean
description: Whether this API Key can manage Recipients
manage_privateBoards:
type: boolean
description: Whether this API Key can manage Private Boards
read_service_maps:
type: boolean
description: Whether this API Key can read Service Maps
visible_team_members:
type: boolean
description: 'Whether this API Key can be accessed by members.
This value is not checked when fetching API keys through the API, there are no permissions check in the
API.
'
ApiKeyCreateResponse:
type: object
required:
- data
properties:
data:
type: object
required:
- id
- type
- attributes
- relationships
- links
properties:
id:
type: string
readOnly: true
description: The unique identifier of the API Key
example: hcxik_12345678901234567890123456
type:
type: string
readOnly: true
enum:
- api-keys
attributes:
allOf:
- $ref: '#/components/schemas/ApiKeyAttributes'
- type: object
required:
- secret
properties:
secret:
type: string
description: The API Key secret. This is the only time it will be returned.
readOnly: true
example: '12345678901234567890123456789'
relationships:
type: object
required:
- environment
properties:
environment:
$ref: '#/components/schemas/EnvironmentRelationship'
creator:
$ref: '#/components/schemas/CreatorRelationship'
editor:
$ref: '#/components/schemas/EditorRelationship'
links:
type: object
properties:
self:
type: string
description: The URL of this resource
readOnly: true
example: /2/teams/my-team/api-keys/hcxik_12345678901234567890123456
UserRelationship:
type: object
required:
- data
properties:
data:
type: object
required:
- id
- type
properties:
id:
type: string
description: 'The ID of this user.
'
examples:
- hcxus_01hzqr5g7jg9qz40xtgx7rjwj0
type:
type: string
enum:
- users
CreatorRelationship:
readOnly: true
description: The User who initially created this resource.
oneOf:
- $ref: '#/components/schemas/UserRelationship'
- type: 'null'
ApiKeyUpdateRequest:
type: object
required:
- data
properties:
data:
oneOf:
- $ref: '#/components/schemas/IngestKeyRequest'
- $ref: '#/components/schemas/ConfigurationKeyRequest'
JSONAPIError:
x-tags:
- Errors
type: object
description: A JSONAPI-formatted error message.
properties:
errors:
type: array
items:
type: object
readOnly: true
required:
- id
- code
properties:
id:
type: string
readOnly: true
status:
type: string
readOnly: true
code:
type: string
readOnly: true
title:
type: string
readOnly: true
detail:
type: string
readOnly: true
source:
type: object
readOnly: true
properties:
pointer:
type: string
readOnly: true
header:
type: string
readOnly: true
parameter:
type: string
readOnly: true
EnvironmentRelationship:
type: object
required:
- data
description: The Environment this object is associated with.
properties:
data:
type: object
required:
- id
- type
properties:
id:
type: string
description: The ID of the Environment this object is associated with.
example: hxenv_12345678901234567890123456
type:
type: string
enum:
- environments
ApiKeyObject:
type: object
properties:
id:
type: string
readOnly: true
description: 'The unique identifier of the API Key.
The last two characters of the prefix define the type of key. `ik` for Ingest Keys and `lk` for
Configuration Keys.
'
example: hcxik_12345678901234567890123456
type:
type: string
readOnly: true
enum:
- api-keys
attributes:
$ref: '#/components/schemas/ApiKeyAttributes'
relationships:
type: object
required:
- environment
properties:
environment:
$ref: '#/components/schemas/EnvironmentRelationship'
creator:
$ref: '#/components/schemas/CreatorRelationship'
editor:
$ref: '#/components/schemas/EditorRelationship'
links:
type: object
properties:
self:
type: string
description: The URL of this resource
readOnly: true
example: /2/teams/my-team/api-keys/hcxik_12345678901234567890123456
ValidationError:
x-tags:
- Errors
allOf:
- $ref: '#/components/schemas/DetailedError'
- type: object
properties:
status:
type: number
readOnly: true
default: 422
type:
type: string
readOnly: true
default: https://api.honeycomb.io/problems/validation-failed
title:
type: string
readOnly: true
default: The provided input is invalid.
type_detail:
type: array
items:
type: object
properties:
field:
type: string
readOnly: true
code:
type: string
readOnly: true
enum:
- invalid
- missing
- incorrect_type
- already_exists
description:
type: string
readOnly: true
IngestKeyAttributes:
title: Ingest Key
allOf:
- $ref: '#/components/schemas/IngestKeyType'
- type: object
required:
- key_type
- name
properties:
key_type:
type: string
description: The type of API Key
enum:
- ingest
example: ingest
name:
type: string
description: A human-readable name for the API Key
example: us-west-2 collectors key
maxLength: 100
disabled:
type: boolean
description: Whether the API Key is disabled
default: false
example: false
permissions:
type: object
description: The permissions granted to this Ingest API Key
properties:
create_datasets:
type: boolean
description: Whether this API Key can create new Datasets
default: false
timestamps:
type: object
readOnly: true
properties:
created:
type: string
format: date-time
description: The ISO8601-formatted time when the API Key was created.
readOnly: true
example: '2022-09-22T17:32:11Z'
updated:
type: string
format: date-time
description: The ISO8601-formatted time when the API Key was updated.
readOnly: true
example: '2022-10-31T15:08:11Z'
ApiKeyListResponse:
type: object
required:
- data
properties:
data:
type: array
items:
$ref: '#/components/schemas/ApiKeyObject'
links:
$ref: '#/components/schemas/PaginationLinks'
ApiKeyCreateRequest:
type: object
required:
- data
properties:
data:
type: object
required:
- type
- attributes
- relationships
properties:
type:
type: string
enum:
- api-keys
attributes:
$ref: '#/components/schemas/ApiKeyAttributes'
relationships:
type: object
required:
- environment
properties:
environment:
$ref: '#/components/schemas/EnvironmentRelationship'
EditorRelationship:
readOnly: true
description: The User who last edited this resource.
oneOf:
- $ref: '#/components/schemas/UserRelationship'
- type: 'null'
ApiKeyAttributes:
type: object
oneOf:
- $ref: '#/components/schemas/IngestKeyAttributes'
- $ref: '#/components/schemas/ConfigurationKeyAttributes'
discriminator:
propertyName: key_type
mapping:
ingest: '#/components/schemas/IngestKeyAttributes'
configuration: '#/components/schemas/ConfigurationKeyAttributes'
ApiKeyResponse:
type: object
required:
- data
properties:
data:
$ref: '#/components/schemas/ApiKeyObject'
PaginationLinks:
type: object
description: Links to iterate through the pages of results.
required:
- next
properties:
next:
type:
- string
- 'null'
description: The URL for the next page of results.
readOnly: true
example: /2/teams/my-team/api-keys?page[after]=3025fa645ad1100d&page[size]=10
DetailedError:
x-tags:
- Errors
description: An RFC7807 'Problem Detail' formatted error message.
type: object
required:
- error
- status
- type
- title
properties:
error:
type: string
readOnly: true
default: something went wrong!
status:
type: number
readOnly: true
description: The HTTP status code of the error.
type:
type: string
readOnly: true
description: Type is a URI used to uniquely identify the type of error.
title:
type: string
readOnly: true
description: Title is a human-readable summary that explains the `type` of the problem.
detail:
type: string
readOnly: true
description: The general, human-readable error message.
instance:
type: string
readOnly: true
description: The unique identifier (ID) for this specific error.
IngestKeyType:
type: object
required:
- key_type
properties:
key_type:
type: string
description: The type of API Key
enum:
- ingest
example: ingest
IngestKeyRequest:
type: object
title: Ingest Key
required:
- id
- type
- attributes
properties:
id:
type: string
pattern: ^hcxik_[a-zA-Z0-9]{26}$
description: The unique identifier of the Ingest Key ID with hcxik_ prefix
example: hcxik_12345678901234567890123456
type:
type: string
enum:
- api-keys
attributes:
type: object
properties:
name:
type: string
description: A human-readable name for the Ingest Key
example: updated key name
disabled:
type: boolean
description: Whether the Ingest Key is disabled
example: false
ConfigurationKeyAttributes:
title: Configuration Key
type: object
required:
- key_type
- name
properties:
key_type:
type: string
description: The type of API Key
enum:
- configuration
example: configuration
name:
type: string
description: A human-readable name for the API Key
example: us-west-2 collectors key
maxLength: 100
disabled:
type: boolean
description: Whether the API Key is disabled
default: false
example: false
permissions:
type: object
description: The permissions granted to this Configuration API Key
properties:
create_datasets:
type: boolean
description: Whether this API Key can create new Datasets
default: false
send_events:
type: boolean
description: Whether this API Key can send Events
default: false
manage_markers:
type: boolean
description: Whether this API Key can manage Markers
default: false
manage_triggers:
type: boolean
description: Whether this API Key can manage Triggers
default: false
manage_boards:
type: boolean
description: Whether this API Key can manage Boards
default: false
run_queries:
type: boolean
description: Whether this API Key can run Queries
default: false
manage_columns:
type: boolean
description: Whether this API Key can manage Columns and Queries
default: false
manage_slos:
type: boolean
description: Whether this API Key can manage SLOs
default: false
manage_recipients:
type: boolean
description: Whether this API Key can manage Recipients
default: false
manage_privateBoards:
type: boolean
description: Whether this API Key can manage Private Boards
default: false
read_service_maps:
type: boolean
description: Whether this API Key can read Service Maps
default: false
visible_team_members:
type: boolean
description: 'Whether this API Key secret can be accessed by members in the Honeycomb dashboard. The user will only
see a redacted key if they aren''t an owner when this setting is enabled.
This parameter has no effect when used through the API since the API never returns the configuration
key secret except at creation.
'
default: false
timestamps:
type: object
readOnly: true
properties:
created:
type: string
format: date-time
description: The ISO8601-formatted time when the API Key was created.
readOnly: true
example: '2022-09-22T17:32:11Z'
updated:
type: string
format: date-time
description: The ISO8601-formatted time when the API Key was updated.
readOnly: true
example: '2022-10-31T15:08:11Z'
Error:
x-tags:
- Errors
type: object
description: A legacy error, containing only a textual description.
properties:
error:
type: string
readOnly: true
parameters:
teamSlug:
name: teamSlug
description: The slug of the Team
in: path
required: true
schema:
type: string
PaginationSize:
name: page[size]
description: The number of entries to include per response. Maximum value is 100.
in: query
schema:
type: number
minimum: 1
maximum: 100
default: 20
example: 10
ID:
name: ID
description: A unique identifier
in: path
required: true
schema:
type: string
PaginationCursor:
name: page[after]
description: 'The string value of the `next` attribute from a previous result page.
The cursor value must be empty or omitted for the first request of a cursor-paginated query.
'
in: query
schema:
type: string
example: eyxJjcmAVhdGVkX
headers:
RateLimitPolicy:
description: "The (draft07) recommended header from the IETF on rate limiting.\nThe value of the header is formatted \"X;w=Y\".\nWhere:\n - X is the maximum number of requests allowed in a window\n\
\ - Y is the size of the window in seconds\n"
schema:
type: string
example: 100;w=60
RetryAfter:
description: 'The RFC7231 header used to indicate when a client should retry requests.
'
schema:
type: string
example: Fri, 22 Mar 2024 18:37:53 GMT
RateLimit:
description: "The (draft07) recommended header from the IETF on rate limiting.\nThe value of the header is formatted \"limit=X, remaining=Y, reset=Z\".\nWhere:\n - X is the maximum number of requests\
\ allowed in the window\n - Y is the number of requests remaining in the window\n - Z is the number of seconds until the limit resets\n"
schema:
type: string
example: limit=100, remaining=50, reset=60
responses:
NotFound:
description: Not Found
headers:
Ratelimit:
$ref: '#/components/headers/RateLimit'
RateLimitPolicy:
$ref: '#/components/headers/RateLimitPolicy'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: dataset not found
application/problem+json:
schema:
$ref: '#/components/schemas/DetailedError'
example:
status: 404
type: https://api.honeycomb.io/problems/not-found
title: The requested resource cannot be found.
error: Dataset not found
detail: Dataset not found
application/vnd.api+json:
schema:
$ref: '#/components/schemas/JSONAPIError'
Unauthorized:
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: unknown API key - check your credentials
application/vnd.api+json:
schema:
$ref: '#/components/schemas/JSONAPIError'
PayloadTooLarge:
description: The provided request body was over the maximum allowed size.
content:
application/json:
schema:
$ref: '#/components/schemas/DetailedError'
example:
status: 413
type: https://api.honeycomb.io/problems/payload-too-large
title: Request body is too large.
error: Body size is larger than maximum size of 100000 bytes
ValidationFailed:
description: Validation Failed
headers:
Ratelimit:
$ref: '#/components/headers/RateLimit'
RateLimitPolicy:
$ref: '#/components/headers/RateLimitPolicy'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ValidationError'
example:
status: 422
# --- truncated at 32 KB (35 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/honeycomb-io/refs/heads/main/openapi/honeycomb-key-management-api-openapi.yml