Scopes & delegated access · Honeycomb Docs

Requested versus effective#

app_scope describes what your app requests. IAM decides what is accepted and currently effective. Application login selects one account and one organization and asks for consent only to critical IAM scopes. Separate OBO consent covers access to other applications. Honeycomb saves requested configuration and displays accepted state separately.

Request access to another application#

{
  "app_scope": {
    "iam": ["self.identity.read", "self.membership.read", "self.tags.read"],
    "external": [
      {"app_id": "briefcase", "endpoint_id": "briefcase.files.read"}
    ]
  }
}

This is a configuration fragment, not a full creation document. Choose only what your app needs. External endpoint IDs come from the provider's registered catalog. For Briefcase, the delegated effective scope is represented as obo:briefcase:briefcase.files.read.

OBO means on behalf of: a service calls a provider for a particular user and selected organization. It does not turn an application credential into unrestricted user authority. Both service configuration and current user authorization matter.

Expose your own endpoints#

{
  "base_url": "https://api.example.com",
  "obo_endpoints": [{
    "endpoint_id": "my-app.documents.read",
    "path": "/api/v1/documents",
    "metadata": {},
    "critical": true,
    "ttl_seconds": 300,
    "enabled": true
  }]
}

The local endpoint_id is stored within the app; IAM exposes the globally unique obo_id [app_id:obo:local_id]. Local endpoint IDs must be unique, nonempty, at most 128 characters, and use letters, digits, dots, underscores, or hyphens. Paths must be absolute endpoint paths without traversal, query, or fragment. TTL must be positive. Exposing endpoints requires a backend base_url origin.

The receiving service must verify IAM's delegated authorization, audience, endpoint, organization context, and relevant permissions. Registering an endpoint does not implement its handler or authorization checks for you.

After an approval changes#

Reconcile accepted application state, then request the appropriate IAM login or separate OBO consent. A changed OBO dependency graph requires a fresh review; an ordinary login does not grant OBO access. Authentication and webhook management cover those transitions.

Browser approval and return flow#

Request OBO when the user chooses a feature that needs it. Open the returned IAM authorization URL in a popup from that click; display=popup selects IAM's compact presentation. Supply your registered redirect_uri callback and bind its state to the initiating application session, account, organization, environment, and pending request.

Your backend exchanges the one-use code and stores the dedicated OBO credentials before confirming completion. The callback can notify the original application window using an exact target origin and a fresh attempt identifier. The opener checks the message origin, source window, and identifier. Access tokens and refresh tokens never belong in browser messages.

Validate any post-completion destination when starting the request and retain it with the pending operation. Do not accept a replacement destination from the callback. Redirect only after the exchange succeeds; without a destination, render a completion page with a return link. Handle popup closure, blocked popups, refusal, expiry, and uncertain exchange responses explicitly. Keep an uncertain exchange recoverable with its original operation identity; do not create another grant or repeat the underlying paid action automatically.

CLI callers may retain a manual URL/code flow. See the IAM OBO contract for authorization, exchange, and receiver verification, and Honeycomb's storage flow for Honeycomb's own return_url and redirect_url fields.

List the user's organization apps#

Honeycomb exposes the critical OBO endpoint honeycomb.apps.list at POST /api/v1/obo/apps/list. It returns every catalog app owned by the selected organization, including private, pending, and disabled entries. State is included so an inventory entry is not mistaken for permission to install or log in. Applications from other organizations are excluded, even when public.

Declare access through Honeycomb:

{"app_scope":{"external":[{"app_id":"honeycomb","endpoint_id":"honeycomb.apps.list"}]}}

Public callers need the provider's critical-scope approval; private callers follow IAM's private-app exemption for that configuration approval. Both still require effective declared access, separate user OBO consent, and current membership in the requested organization. Application credentials alone cannot authorize an organization inventory.

Use IAM's endpoint catalog to request separate OBO authorization for audience honeycomb, endpoint ID honeycomb.apps.list. The user reviews the complete dependency chain and selects an account and organization for each provider. The originating app redeems the single-use authorization code and securely stores the OBO refresh credential. Send the resulting access token:

POST /api/v1/obo/apps/list
Content-Type: application/json
X-IAM-OBO-Access-Token: <OBO access token>

{"org_id":"tos","limit":100}

The response is deliberately limited to catalog identity and status:

{"org_id":"tos","items":[{"app_id":"internal","org_id":"tos","name":"Internal","description":"Organization application","visibility":"private","state":"active"}],"next_cursor":null}

limit defaults to 100 and accepts 1–100. If next_cursor is present, send its value as after in the next request using the same unexpired access token. Rows are ordered by app_id. Configuration, webhook secrets, app credentials, testing keys, and unpublished configuration details are never returned. Honeycomb authenticates as the receiving application and verifies the token with IAM on every request against the registered endpoint, method and path. Tokens are reusable, do not bind the body digest, and are not consumed. Expired, revoked or mismatched authority is rejected. A declared downstream provider can receive the same chain token and verify its own endpoint. Verification returns that provider's approved account and organization. Consent persists until revoked; current membership, security epochs and graph changes still govern credentials. Verification does not disclose a user's org role unless IAM authorizes that separate scope, and listing does not require an admin role or self.identity.read disclosure.

For a test environment, pass X-Testing-Environment-Key. Honeycomb resolves only that ready environment, recovers its own recipient credential through the protected IAM integration, and verifies the access token there. The token's environment must match; invalid keys, cleanup, and mismatched credentials never fall back to production. This selects an isolated testing environment, independently of a package's dev/prod release channel.

Users with a Honeycomb login can request the same inventory through GET /api/v1/organizations/{org}/apps?limit=100&after=..., authenticated with their Honeycomb bearer token. Current members, including Silicon users, have access; other organizations and anonymous callers do not.

Registering this provider endpoint#

The backend advertises the definition through /api/contracts under obo_endpoints. For deployment, merge the definition from deploy/honeycomb-obo.json into Honeycomb's existing application configuration, then submit it through Honeycomb's normal configuration/IAM reconciliation flow. Preserve existing endpoint definitions and configuration. The definition is critical, enabled, and uses a 60-second access-token TTL. Shipping the HTTP handler alone does not register its scope in a running IAM instance. Each existing testing import must be explicitly refreshed to receive the new definition; production configuration does not silently change test snapshots.