Skip to main content
Status: Accepted Date: 2026-02-06 Deciders: Reflections Maintainers

​
Context

The product supports share links for public voice interaction. This creates a deliberate anonymous entrypoint that must remain tightly scoped to avoid bypassing normal authenticated RBAC controls.

​
Decision

Model share access as an explicit bounded public surface:
  • Anonymous routes are isolated under /v1/r/:token and do not use authenticated middleware.
  • Session creation from a share link consumes link usage atomically and rolls back use count on session creation failure.
  • Share links are namespace-scoped, optionally expiring, and optionally use-limited.
  • Reflection admins create/revoke share links through authenticated admin-only routes.

​
Alternatives considered

​
Alternative 1: Disable anonymous sharing entirely

Pros:
  • Simpler security posture.
  • No public attack surface for reflection interaction.
Cons:
  • Removes a core product capability.
  • Reduces collaboration and external demo workflows.

​
Alternative 2: Reuse authenticated session endpoint for share flows

Pros:
  • Fewer route handlers.
Cons:
  • Blurs security boundaries between anonymous and authenticated access.
  • Harder to enforce share-token-specific constraints.

​
Alternative 3: Token as full API credential

Pros:
  • Flexible for external integrations.
Cons:
  • Excessive privileges for link-based access.
  • Larger blast radius if token leaks.

​
Consequences

Benefits:
  • Clear and auditable anonymous-access boundary.
  • Stronger control over shared scope and lifecycle.
  • Preserves admin authority over share creation and revocation.
Costs:
  • Additional route and token-lifecycle logic.
  • Need continued abuse-rate monitoring for public endpoints.

​
Implementation notes

  • Public share routes are isolated in a dedicated route module.
  • Share lifecycle management for admins is in a separate admin-scoped route module.
  • Rate limiting for public share paths is configured at the API level.