honeycombDocs
Publish an app / HONEYCOMB

Application configuration

A field-by-field guide to registration and configuration updates.

A complete creation input#

Save the following as a protected JSON file. Replace the example organization, receiver, and signing secret before submitting. The description intentionally meets the minimum word count.

{
  "org_id": "my-org",
  "local_app_id": "my-app",
  "name": "My application",
  "description": "My application helps members of our organization prepare, inspect, and share project work from a consistent command line interface. It provides native builds for supported desktop and server platforms, uses IAM for identity and permissions, and keeps organization data separated. This application is maintained by our team and is intended for authorized members working on shared projects.",
  "webhook_url": "https://api.example.com/webhook/",
  "webhook_secret": "REPLACE_WITH_A_PRIVATE_RANDOM_SECRET",
  "webhook_scope": ["membership"],
  "app_scope": {"iam": ["self.identity.read"], "external": []},
  "obo_endpoints": [],
  "testing_idle_days": 30
}

Generate a random signing secret with a secure generator such as openssl rand -hex 32, store it privately, and configure the same value at your receiver. Download the example.

Required fields#

Field Rules
org_id Existing shared organization; caller must be a current owner/admin.
local_app_id Permanent local handle. Handles use 1–64 lowercase letters, digits, or hyphens; begin with a letter or digit.
name Nonempty display name, at most 100 bytes under the current validator.
description 50–1,000 whitespace-separated words.
webhook_url HTTPS destination without embedded credentials.
webhook_secret At least 32 characters for creation; protect it like a credential.

The resulting ID is org_id>local_app_id. Updating configuration does not rename the application's identity.

Optional fields#

Field Default / purpose
logo_url Optional HTTPS logo. Uploaded logo links are public.
website_url, docs_url Optional HTTPS links.
base_url Backend origin for exposed OBO endpoints; no path, query, or trailing slash.
webhook_scope Categories from membership, updates, trust, full.
app_scope.iam Requested IAM scope names.
app_scope.external Provider application and endpoint pairs.
obo_endpoints Endpoints your application exposes for delegated access.
obo_review_message Context for permission reviewers.
testing_idle_days 30 by default; range 1–36500.

Unknown input fields are rejected. Requested and effective configuration are displayed separately because IAM must accept changes before they apply at runtime.

Update safely#

honeycomb apps get 'my-org>my-app' --json
honeycomb --idempotency-key my-app-config-0002 apps update 'my-org>my-app' application.json --revision 2

Use the actual current revision and a complete configuration document. On updates, an empty or omitted signing secret retains the existing stored secret when available. Existing legacy apps without stored configuration need a supported adoption workflow; do not recreate their identity to work around this.

Shared drafts#

honeycomb drafts list my-org
honeycomb drafts save my-org draft-handle draft.json --revision 0

A new draft starts at revision 0; later saves use the latest draft revision. Drafts let another current organization admin continue the work. They are not active IAM applications, and secrets/files are not persisted as draft fields.