> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reflections.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# ADR-0017: Public share-link and anonymous session boundary

> Allow public reflection access via constrained anonymous sessions without exposing privileged reflection data surfaces.

<Info>**Status:** Accepted **Date:** 2026-02-06 **Deciders:** Reflections Maintainers</Info>

## 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.

## Related ADRs

* [ADR-0008: Authentication and RBAC model](/decisions/adr-0008)
* [ADR-0009: API architecture and authorization enforcement](/decisions/adr-0009)
* [ADR-0015: Tenant isolation and database RLS boundary](/decisions/adr-0015)