Topolo Auth API

Important route families

• authentication and session validation
• browser SSO authorize, exchange-code completion, and bearer-backed handoff-code creation
• organization and service registry queries
• credential-scoped action catalog 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
• internal billing-plane provisioning: passwordless workspace creation from a completed checkout and live workspace-URL availability lookup

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
• GET /api/actions/catalog returns only machine-callable actions whose service permission is already granted to the current credential; apps publish those actions through Topolo Developers and Auth rejects action definitions that reference undeclared service permissions
• 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
• app-switcher preferences persist user-level launcher choices and platform shell theme through GET and PUT /api/app-switcher/preferences, including favorites, hidden, tileSize, and optional theme: "light" | "dark"
• first-party service-scoped login resolves a personal active context to the single organization membership that has access to the requested organization-only service before issuing the destination token
• 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
• Topolo Developers is also the only authoring surface for app action definitions. It syncs approved action metadata into Auth through the internal POST /api/internal/service-actions/sync route, and public SDK/CLI/MCP consumers read the credential-scoped projection from GET /api/actions/catalog
• 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

Internal billing-plane provisioning

These routes back the TopoloOne signup-from-checkout flow. They authenticate with a keyless S2S service token (verifyServiceToken) and are restricted to billing-plane service identities by slug allowlist (topolo-pay, topolo-one-website, topolo-one-api); no user JWT is involved. Because Auth is the token issuer, it verifies these inbound service tokens against its own LOCAL JWKS rather than HTTP-fetching its own hostname.

• POST /api/internal/provision-from-checkout — passwordless workspace provisioning from a completed checkout. Creates the organization plus a passwordless owner identity (role owner, empty password hash), seeds the org’s app entitlement on organizations.settings.appEntitlement, grants the default platform services plus the target service, and issues a single-use magic-login token whose consume URL is returned as loginUrl so the marketing success page can drop the user straight into the dashboard with no “Create Account” screen. Idempotent by email: it resolves the owner’s existing org by membership (the org they own, not just active context) and re-issues a fresh login token instead of creating a duplicate workspace. On FIRST provision only (created: true) it also emits a separate, longer-TTL safety-net magic link by email (this emailed token KEEPS the anti-prefetch interstitial). Request body: email, workspaceName (or company), serviceId, redirectUri (validated against the service entrypoint), optional name, and an entitlement snapshot (mode of count | all | free, optional paidAppCount, optional appSlugs). Returns { orgId, userId, created, loginUrl, expiresAt }.
• GET /api/internal/organizations/slug-availability?slug=<slug> — live workspace-URL availability for the signup form’s Google-style “is this taken?” check. Validates format (lowercase alphanumeric with internal hyphens, 3–48 chars), screens a reserved-subdomain set, then checks getOrganizationBySlug. Read-only and idempotent; returns { available, slug, reason } with reason one of available, taken, invalid, reserved, or empty.

The magic-login token issued by provisioning sets the new magic_login_tokens.skip_interstitial flag (migration 0029). A trusted in-session token auto-consumes on GET /magic-link/consume, skipping the anti-prefetch “Confirm sign-in” interstitial that protects email-delivered links; both the GET fast path and the POST confirmation share completeMagicLinkSignIn.