Topolo Auth | Topolo Docs

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, the low-friction developer-workspace signup contract used by developers.topolo.app, and the narrow approved-app registration handoff consumed when Developers review approves an 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. The compatibility account-settings URL at https://auth.topolo.app/settings redirects signed-in browser users to Topolo Admin’s /security/user route, because Auth owns identity APIs while Admin owns the security-settings UI.

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
POST /register with developerWorkspace=true plus createOrganization=true for low-friction developer-workspace signup
GET /api/developers plus PATCH /api/developers/:developerId/status for authenticated operator review

Auth and Permissions

Auth is the source of truth for service IDs, API key scopes, service permissions, and bindable resource catalogs. Resolved user permissions are published in the canonical serviceId.resource:action shape. First-party and third-party apps should integrate through the shared browser client and middleware packages instead of inventing app-local token parsing or wildcard logic. Those shared clients now default missing role claims to member and keep platform roles (platform_super_admin, platform_admin) distinct from org-scoped roles (owner, super_admin, admin, member, guest). Authenticated admin inspection of a user’s permissions now returns the evaluated permission set plus source breakdowns for org service access, role bundles, and user overrides. Service registrations are only considered complete when permissions, role bundles, API key scopes, and docs coverage are all present. Auth now treats platform_super_admin, platform_admin, owner, super_admin, admin, member, and guest as the canonical built-in role ladder. Platform-wide bypass remains limited to platform_super_admin and platform_admin users in the admin organization, while same-org owners, org super admins, and admins retain elevated access only on organization-scoped admin routes such as sessions, security, password reset, and user-permission management. Access-token validation also rehydrates the current stored role and active org context before Auth authorizes those org-scoped admin routes, so recent role changes do not leave browser or CLI calls stuck behind stale JWT claims until the next refresh. Service catalog responses also publish surface classification so clients can distinguish launchable applications from APIs, runtimes, and internal platform services without relying on names or local permission prefixes. The checked-in service manifests now drive production API-key scope rows for drift-sensitive platform and third-party services. Developer workspaces now reuse Auth organizations as the canonical owner for private apps and API keys. That means developer-console keys still use the central Auth API-key model, and suspended or revoked developer workspaces should be blocked at the Auth mutation layer instead of only by frontend UI.

Data Ownership

Auth owns the canonical API key scope catalog, resource binding catalog, service registration, permission metadata, and the approved-app registration handoff that Topolo Developers consumes after application review.

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

Replaced the temporary hosted Auth account settings page on 2026-04-19 with a redirect to Topolo Admin /security/user, keeping Auth as the identity API owner while Admin remains the security-settings frontend.
Corrected shared Auth client role normalization on 2026-04-24 so browser, headless, and Flutter consumers default missing role claims to member and preserve the canonical platform-versus-organization role split.
Corrected Auth access-token validation on 2026-04-24 so org-scoped admin routes rehydrate the current stored role and active context instead of trusting stale JWT role claims until the next refresh.
Corrected public Auth admin-route behavior on 2026-04-24 so same-org owners, admins, and non-admin-tenant super admins keep elevated access on org-scoped session, security, password-reset, and user-permission routes while platform-wide bypass stays limited to the Auth admin tenant.
Added service surface classification on 2026-04-23 so launcher and admin clients can separate applications from API/runtime/internal services using Auth catalog metadata.
Synced production API-key scope rows for Nexus, Messaging, and third-party services on 2026-04-19 so live D1, generated seed SQL, and manifest permission contracts agree.
Removed the legacy Topolo Developers backend aliases from Auth on 2026-04-15 so /api/developer-portal/*, /api/app-submissions, and /api/build-requests are no longer published from the identity runtime after the Developers ownership cutover
Added the account-first developer-console Auth contract on 2026-04-13 so developer signup can seed an Auth organization workspace, the new /api/developer-console/* routes now drive onboarding and private app records, and developer-workspace API-key access is still enforced through the central Auth key model
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
Clarified the public Auth contract on 2026-04-10 so resolved permissions now use the canonical serviceId.resource:action shape and the authenticated inspection surface returns evaluated permissions with source breakdowns
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