Authentication

Core model

Topolo Auth owns:

• user identity
• organization membership and role resolution
• service registration
• service permissions
• API key scopes and resource bindings
• workspace lifecycle and the caller-specific creation policy for each target application

Downstream applications trust Auth for the authorization context they consume.

Authentication is not the same as product entitlement. A Topolo account identifies the person; application access can still depend on organization membership, app install state, service grants, app-owned membership, invite activation, free-app policy, or a paid plan. Third-party applications using Topolo for login should create or link their own local account after Auth returns a one-time sso_code, then apply their own access and billing rules.

For CLI and MCP agents, OAuth scope is also not the final action decision. The credential-scoped application and action catalogs project current service access and permissions, while actions marked authorizationMode: "runtime" defer the final decision to the target application for the concrete input and resource. Agents should treat a target 403 as authoritative rather than retrying through an inferred endpoint.

The CLI OAuth device-approval page is owned and served by Topolo Auth at the environment's Auth origin. Topolo Developers owns developer application management and OAuth client configuration; it does not own a second device-approval surface.

Session and access flow

1. A user authenticates with Topolo Auth.
2. Topolo Auth issues the access context used by the client or middleware.
3. Service backends validate the presented credentials with Auth when current role or permission resolution matters.
4. Protected application routes authorize against the resolved service permissions or API key scopes.

Admin-sensitive behavior

Admin-only surfaces such as API key management rely on the current Auth-resolved org role, not just stale token claims. This keeps operator permissions consistent across applications.

Passkeys

Topolo passkeys use WebAuthn with user verification required. Auth owns the one-time registration and authentication challenge state and verifies the browser origin, relying-party identity, authenticator signature, and replay counter before accepting a credential. Applications should use the shared Topolo login and security-management components rather than constructing passkey challenges locally.

Where to debug

Use the internal Auth handbook for current routes, backing tables, and debugging steps when a service appears to disagree about the user role or allowed action.

Change Log / Verification

• Reverified Auth ownership on 2026-08-14 against @topolo/cli 0.8.6 and the current Auth/Developers split: device approval is Auth-owned, while Developers manages OAuth clients and developer application configuration.

• Clarified OAuth scope versus credential-scoped and target-owned runtime action authorization for clean-room agents on 2026-07-14.

• Enabled cryptographically verified WebAuthn registration and assertion handling on 2026-07-12, including single-use server challenge state and clean re-enrollment for credentials created by the retired placeholder verifier.

• Reconciled docs freshness on 2026-06-28 against topolo-platform through 20653c79; latest commit reviewed was 20653c79 feat(auth): bulk availability + app_id-mapping endpoints (seed subrequest cap), with recent context 20653c79 feat(auth): bulk availability + app_id-mapping endpoints (seed subrequest cap); 61117a0d feat(app-shell): add lazy component factory; d8784cfa feat(app-shell): add canonical lazy route factory.

• Clarified on 2026-04-21 that Topolo authentication identifies the person while application entitlements and billing can remain app-owned or organization-owned.