> ## 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-0009: API architecture and authorization enforcement

> Keep API boundaries explicit with consistent route-level authn/authz and error semantics.

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

## Context

The API exposes reflection-scoped and public routes. Unauthorized data access risk is high unless every protected route consistently applies authentication and role checks.

## Decision

Use Hono as the API boundary and require route-level security discipline:

* Protected route groups call `authMiddleware()`.
* Reflection/resource-scoped handlers call `requireReflectionRole` or `requireResourceRole`.
* Public routes are explicitly isolated in dedicated route modules.
* Global error mapping in `app.onError` standardizes response shapes.

## Alternatives considered

### Alternative 1: Framework-level global auth with route exceptions

Pros:

* Less repeated middleware declarations.

Cons:

* Exception paths become easy to misconfigure.
* Harder to reason about per-route role requirements.

### Alternative 2: Inline auth checks in each handler without shared helpers

Pros:

* Local visibility of checks.

Cons:

* Duplication and inconsistent enforcement.
* Higher chance of drift in permission semantics.

### Alternative 3: GraphQL gateway with resolver-level policies

Pros:

* Centralized schema contract and policy hooks.

Cons:

* Significant complexity increase for current REST surface.
* Migration cost without clear short-term benefit.

## Consequences

**Benefits:**

* Predictable, reviewable authn/authz pattern across routes.
* Clear public vs protected API boundary.
* Centralized error transformation for stable client behavior.

**Costs:**

* Requires sustained route review discipline.
* Middleware/setup repetition across route modules.

## Implementation notes

* API composition and global middleware are defined in the main API entrypoint.
* Route security patterns follow a consistent middleware-first approach across all route modules.
* Public endpoints are intentionally grouped in a dedicated public route module.

## Related ADRs

* [ADR-0008: Authentication and RBAC model](/decisions/adr-0008)
* [ADR-0006: DB query surface segregation](/decisions/adr-0006)
* [ADR-0011: Observability and tracing strategy](/decisions/adr-0011)