public active Last verified 2026-04-10

Topolo Auth

Public overview of identity, service registration, API keys, and permission ownership across the platform.

Owners
identity-platform
Source Repos
PlatformApplications/TopoloAuth
Systems
Topolo Auth, Topolo Platform
Tags
identity, auth, api-keys

What It Is

Topolo Auth is the platform identity and authorization service. It owns user auth, org membership, service registration, permissions, and centralized API key scope catalogs.

Architecture

Auth is a dedicated service with its own worker/runtime surface, D1-backed catalogs, and platform-wide responsibility for validating access context. Its public surface includes interactive login, OAuth and SSO flows, service registration, API-key scope/resource catalogs, machine-oriented auth handoff patterns, Turnstile-protected intake routes used by TopoloOne’s public developer funnel, and the authenticated route family used by the dedicated developers.topolo.app application.

Topolo browser applications standardize on a single cookie-backed refresh contract through the shared browser auth client rather than app-local session refresh implementations. Headless JavaScript and TypeScript clients standardize on the same shared auth package for direct credential login and bearer-token validation instead of app-owned Auth protocol code.

Runtime Surfaces

The primary Auth hostname is https://auth.topolo.app.

API Reference

Use /reference/api/topolo-auth and /reference/apps/topolo-auth for the current route families and API-oriented contract surface. The canonical docs application now replaces the old repo-local guides for OAuth setup, passkeys, permission modeling, service APIs, cookie/session behavior, and security troubleshooting.

The current public and admin-adjacent route families also include:

  • POST /api/public/developers/apply for TopoloOne developer-program intake
  • POST /api/public/app-submissions for TopoloOne app-submission intake
  • GET/PUT /api/developer-portal/profile for signed-in developer profile setup
  • GET/POST /api/developer-portal/app-submissions for signed-in developer submissions
  • GET/POST /api/developer-portal/build-requests for community-benefit and company-specific build requests
  • GET /api/developers plus PATCH /api/developers/:developerId/status for authenticated operator review
  • GET /api/app-submissions plus POST /api/app-submissions/:submissionId/review for submission review and approval workflows
  • GET /api/build-requests plus POST /api/build-requests/:requestId/review for operator review of authenticated developer build requests

Auth and Permissions

Auth is the source of truth for service IDs, API key scopes, service permissions, and bindable resource catalogs.

Data Ownership

Auth owns the canonical API key scope catalog, resource binding catalog, service registration, and permission metadata that other apps consume.

Deployments

Auth deploys as a Cloudflare-backed runtime surface with D1-backed data catalogs and route validation. Its cross-origin cookie-backed refresh surface must continue to allow the X-Topolo-Auth and X-Service-ID request headers used by Topolo web applications during session rehydration. That origin policy also needs to cover the first-party Cloudflare Pages project domains and preview subdomains used by Topolo browser applications, plus the shared /session/channel and /session/broadcast-logout iframe routes those apps use for logout propagation.

Failure Modes

  • stale user or service context
  • missing service catalog rows for scopes or permissions
  • mismatched service IDs between docs and Auth seeds
  • browser apps drift back to custom refresh clients instead of the shared contract
  • headless or CLI runtimes drift back to app-local Auth login and token-validation clients

Debugging

Start with /systems/topolo-auth, then inspect the API and machine artifacts for the relevant service or catalog route.

Change Log / Verification

  • Added full Topolo developer-platform route coverage on 2026-04-10, including Turnstile-protected TopoloOne public intake, the authenticated developers.topolo.app profile/submission/build-request routes, and shared operator review endpoints for developer, submission, and request state
  • Standardized Topolo browser applications on the shared cookie-refresh auth client on 2026-03-31
  • Standardized the JavaScript and TypeScript headless auth contract on the shared Topolo auth client on 2026-03-31
  • Verified the cross-origin refresh contract for Topolo web applications, including X-Topolo-Auth and X-Service-ID preflight handling plus first-party Pages/session-channel origin coverage, on 2026-03-31
  • Expanded canonical Auth coverage and retired repo-local Auth guides on 2026-03-30