Third-Party Auth Integration

What It Is

This is the canonical Topolo Auth guide for third-party developers integrating an external application with the Topolo identity service.

Integration Model

Third-party integrations should expect:

Auth hosted at https://auth.topolo.app
registered service IDs and allowed origins
a service permission catalog and default role bundles defined in Auth before rollout
JWT-based session or bearer-token validation
support for redirect or popup login flows
OAuth and cross-domain SSO entry patterns where applicable
public service login metadata that reflects the auth methods actually available for that service
service-local identities for non-seated portal users where the application owns account membership and Auth owns identity brokerage

Account And Access Model

Topolo Auth is the identity provider. It proves who the person is and returns a one-time OAuth authorization code, or an sso_code for SSO/native handoff flows, to the registered application callback. The third-party application remains responsible for its own customer accounts, tenants, plans, trials, invitations, and product access.

A user may create a Topolo account during the login flow and still have no access to the third-party application until that application creates or links a local account and applies its own entitlement rules. Do not treat a Topolo identity as proof of subscription, plan status, workspace membership, or app-specific authorization.

The expected third-party sequence is:

Register the application, callback URLs, scopes, and service metadata in Topolo Developers.
Send the user to Topolo Auth for sign-in or signup.
Auth shows the consent page at auth.topolo.app/developer-oauth/consent, including publisher, callback domain, trust state, and requested scopes, and records approval or denial as an Auth audit event.
Receive a one-time authorization code on the registered callback.
Exchange the code from the application backend or trusted client path.
Create or link the local app account.
Decide app access from the app’s own free, paid, trial, invite-only, or suspended state.

Core Flows

The supported topics are:

service registration, permission naming, and role-bundle setup
frontend login entrypoints
backend token verification and middleware
token storage and session management
cross-domain SSO
permission and authorization handling
environment configuration
security and troubleshooting guidance
third-party login surfaces that use Auth as an identity broker while keeping customer-account ownership inside the application
service-managed magic-link issuance for external contacts, followed by application-owned invite activation and entitlement checks

Canonical Rule

First-party Topolo applications use the first-party Auth standard documented in the docs platform. This guide exists for external integrations and replaces the old repo-local third-party integration file. The canonical third-party path is: register one service for the application, define the permission catalog, define default role bundles, configure allowed origins and callback/login metadata, use the shared auth client and middleware, then validate tokens with that service context on every backend route. Third-party apps should follow the same enforcement rule as first-party apps: Auth permissions grant access, and any app-local roles, workspaces, projects, or customer-tenancy records may only narrow access inside the product domain. Do not add local SKIP_AUTH paths, raw role-string heuristics, or legacy permission aliases alongside the shared Topolo Auth SDK path. When a third-party product owns its own customer-account model, Auth should remain the identity layer only. That means the application may keep customer tenants, memberships, invites, and partner entitlements in its own database while Auth continues to own provider discovery, token issuance, refresh, and any hosted or service-authenticated magic-link flows. Do not create a second Topolo service for a partner area, customer portal, supplier login, or other sub-surface of the same third-party application; those routes use the owning application service id, and the application decides the local account or invite entitlement after Auth proves the identity. Auth supports per-service magic-link delivery ownership: topolo_managed lets Auth issue and send the link, while service_managed lets Auth issue the one-time link and return it only to the trusted service backend so the application can send mail from its own domain and provider account. Public login surfaces should consume available_auth_methods rather than guessing from provider names alone, because Auth may hide a method until the matching provider secrets, service API key, or delivery path actually exists. Installable clients can also declare native callback schemes and exact callback URLs in service metadata so Auth can return one-time sso_code callbacks to the native app; the app must redeem the code through /sso/exchange and must not accept bearer tokens in callback URLs. Third-party browser applications that want the shared app launcher should consume AppLauncher or TopoloAppShell from @topolo/ui-kit, pass an in-memory Topolo access token via getAccessToken, and leave storeUrl on its default https://developers.topolo.app unless they are targeting a Developers-compatible environment. The launcher uses Developers for catalog/search reads and the app-origin Auth gateway for preference, assignment, install, and SSO handoff mutations; third-party apps must not read Auth’s internal store catalog directly. Publisher-owned quick links belong in Developers app metadata so the launcher can surface approved app-internal destinations without hardcoded third-party routes.

Next Steps

Start with /guides/authentication for the shared Auth model.
Use /applications/auth and the Auth references for the current service and route families.
Coordinate service registration, permission catalog setup, role-bundle setup, and allowed-origin configuration before implementing login flows.

Change Log / Verification

Updated native callback guidance on 2026-04-18 so installable clients use one-time sso_code exchange and do not accept bearer-token callback URLs.
Added shared launcher guidance on 2026-04-28 so third-party browser apps use the Developers catalog boundary and shared @topolo/ui-kit launcher instead of reading Auth catalog APIs directly.
Clarified on 2026-04-23 that partner/customer/supplier sub-surfaces of one third-party app must stay under the owning application service id instead of becoming separate Topolo services.
Clarified the third-party account and access model on 2026-04-21 so Topolo signup creates identity while app-specific entitlements remain owned by the third-party product.
Clarified on 2026-04-21 that browser OAuth consent is hosted by Auth and can be approved by any signed-in Topolo identity, while Topolo Developers owns client registration and review.
Added consent audit guidance on 2026-04-21 so third-party approvals and denials are traceable by client, callback domain, scope set, trust state, and signed-in actor.
Added canonical third-party Auth integration guidance and retired the repo-local guide on 2026-03-30
Expanded the third-party integration path on 2026-04-10 so external apps now follow the same service-registration, permission-catalog, role-bundle, and shared-client/middleware contract as first-party apps
Added the application-owned customer-account plus Auth-brokered magic-link pattern for third-party login surfaces on 2026-04-11
Added per-service magic-link delivery ownership guidance on 2026-04-11 so third-party apps can keep email delivery and sender reputation inside their own product boundary
Added guidance for service-declared native callback allowlists on 2026-04-11 so third-party apps can complete brokered sign-in back into native clients without opening the browser admin flow
Clarified the conformance rule on 2026-04-11 so third-party apps now have one supported path: shared Topolo Auth client and middleware, canonical Auth permission grants, and local domain roles only as narrowing controls
Clarified the supported non-seated external-contact pattern on 2026-04-16 for service-local identities, service-managed magic links, and application-owned entitlement checks