Skip to main content
← Back to list
01Issue
FeatureTriagedSwamp ClubPublic
Assigneesstack72

Relationships

↔ sibling #4726↔ sibling #4708↔ sibling #4698↔ sibling #4685

#4727 Document trusted telemetry endpoint and authentication semantics

Opened by stack72 · 11/13/2026

Documentation surface

The canonical user documentation is the Swamp Club manual in the swamp-club site. This change belongs there, not in the CLI repository README.

Problem

The manual documents telemetryEndpoint resolution and separately documents that signed-in telemetry sends the active API key for attribution. It does not state their combined trust contract: authenticated telemetry sends that key to the resolved telemetry endpoint.

This is intentional for operator-controlled and in-prem telemetry collectors, but the trusted deployment boundary needs to be explicit.

Requested documentation

Update these existing manual pages:

  • content/manual/reference/repository-configuration.md, under telemetryEndpoint: identify it as trusted deployment configuration for an operator-controlled collector.
  • content/manual/reference/usage-telemetry-events.md, under Endpoint: state that the resolved endpoint is also the destination for the authentication header when telemetry is attributed.
  • content/manual/explanation/usage-telemetry.md, under Attribution: connect API-key attribution to the resolved endpoint and link to the endpoint reference.

Acceptance criteria

  • Document endpoint precedence: SWAMP_TELEMETRY_ENDPOINT, repository marker, localhost auto-detection, then the hosted default.
  • State that custom telemetry endpoints must be controlled by the trusted deployment operator.
  • State that signed-in telemetry forwards the active API key using the x-api-key request header to the resolved endpoint for attribution.
  • Provide guidance for organization-managed and in-prem telemetry collectors.
  • Clarify that repository telemetry configuration is trusted deployment configuration, not a security boundary intended for arbitrary public repository content.

Non-goal

This issue does not add origin restrictions. Any future credential-to-origin binding must support managed in-prem deployments without breaking authenticated telemetry.

02Bog Flow
✓OPEN◉TRIAGED○IN PROGRESS○SHIPPED+ 5 MOREISSUE_LINKEDCLASSIFICATION

Triaged

11/13/2026, 8:07:36 PM

Click a lifecycle step above to view its details.

03Sludge Pulse
stack72 assigned stack7211/13/2026, 8:05:57 PM
stack72 linked sibling of #472611/13/2026, 8:06:36 PM
stack72 linked sibling of #470811/13/2026, 8:06:40 PM
stack72 linked sibling of #469811/13/2026, 8:06:45 PM
stack72 linked sibling of #468511/13/2026, 8:06:49 PM

Sign in to post a ripple.