Topolo Auth API | Topolo Docs

Important route families

authentication and session validation
browser SSO authorize, exchange-code completion, and bearer-backed handoff-code creation
organization and service registry queries
service API key scopes
service API key bindable resources
API key create, list, revoke, and validation flows
developer-workspace signup and approved-app registration handoff for Topolo Developers

Why this page exists

Topolo Auth exposes platform semantics that are broader than a raw endpoint index. Use this page for behavioral guidance, then use generated reference where a formal spec exists for a downstream service.

Operational contract

resolved user permissions are emitted in the canonical serviceId.resource:action form
GET /api/users/:userId/permissions returns the evaluated permission payload for authenticated inspection, including effectivePermissions, effective permission entries, and source breakdowns for org service access, role bundles, and user overrides
Auth user payloads may now also expose explicit external-identity context through principalType, principalServices, and launcherEligible, so downstream control-plane surfaces do not need to infer service-local users solely from missing organization membership
service scope metadata for API keys is served from Auth D1
service catalog responses include surface_kind, surface_group, and launchable so clients can separate human applications from APIs, runtimes, and internal support services
default role bundles for each registered first-party service are served from Auth D1 alongside the service permission and API key scope catalogs
resource-binding catalogs for supported services are also served from Auth D1
clients should not hardcode service scope lists or fetch bindable resources directly from application UIs
browser clients should use PlatformApplications/packages/topolo-auth-client and service backends should use PlatformApplications/packages/topolo-auth-middleware for login, refresh, token validation, and permission matching semantics
service backends must not authorize protected routes from locally decoded JWT claims alone; successful bearer-token authorization requires Auth /validate, and Auth validation outage should fail closed
app-switcher service-listing routes honor an explicit Authorization: Bearer … token before falling back to auth cookies, so stale browser cookies do not override the caller’s current in-memory session
app-switcher launches use POST /sso/handoff-code with Authorization: Bearer …, service_id, and redirect_uri to create a single-use destination callback URL before browser navigation; the response never contains a bearer token in the URL
the retired browser /sso/handoff bridge is not part of the active route contract
developer-console workspaces are Auth organizations under the hood, so developer app records and API keys stay org-scoped and reuse the same ownership model as the rest of the platform
POST /register can now seed a developer workspace when called with developerWorkspace=true and createOrganization=true, assigning the creator as org owner
Topolo Developers owns the signed /api/developer-console/* route family directly. Auth no longer publishes /api/developer-portal/* or the older review aliases and remains the identity, central API-key, and approved-app registration authority used by that console
developer workspaces should continue to read service scope catalogs from Auth instead of shipping app-local scope lists, and suspended or revoked developer workspaces should be blocked from mutating central API keys through the same Auth endpoints