Topolo Auth Handbook | Topolo Internal Handbook

What It Is

Topolo Auth is the platform identity and authorization source of truth for user context, service IDs, scopes, permissions, sessions, and machine credentials.

Architecture

Auth is implemented as a dedicated runtime surface with controller, repository, and seed/catalog layers, backed by D1 catalogs for service and API key metadata.

Runtime Surfaces

The primary runtime host is auth.topolo.app.

API Reference

Use the Auth reference pages and generated machine artifacts for current route families, scope catalogs, and service metadata outputs.

Auth and Permissions

Auth owns the checked-in permission seeds, API key scope seeds, service registration, and validation routes used across the platform.

Data Ownership

Canonical ownership includes service IDs, API key scope catalogs, bindable-resource catalogs, role/permission catalogs, and access validation state.

Deployments

Auth deploys as the platform identity runtime and must stay aligned with checked-in seeds and migration scripts.

Failure Modes

stale role or session context
missing scope rows in checked-in seed data
service ID drift between runtime and docs

Debugging

inspect Auth seed files first
confirm the service ID in the system registry and Auth catalog
verify controller and repository alignment for the failing route family

Change Log / Verification

Verified against the current Auth catalog and API key resource-binding architecture on 2026-03-29