Auth And Identity

What It Is

Topolo Auth is the authoritative service for user identity, organization membership, role resolution, service registration, service-level permissions, and API key state.

How It Works

Clients authenticate through Auth and downstream services validate or consume that auth context. For privileged surfaces, service backends should prefer a fresh Auth-derived context over stale token-only role claims.

Interfaces

• auth/session routes in Applications/TopoloAuth/src/index.js
• shared auth resolution in Applications/packages/topolo-auth-middleware
• service registry, service permission, and API key routes in Applications/TopoloAuth/src/controllers/auth.js

Data Flow

1. A client presents an access token.
2. Auth resolves the current user, org, and role context.
3. Downstream services consume that context for authorization.
4. Admin-only surfaces rely on the current Auth-resolved role.

Failure Modes

• stale locally trusted token role claims disagree with current Auth state
• service permission catalogs drift from operator expectations
• service IDs do not match the registry entry being queried

Debugging

• confirm the current service ID in the service registry
• inspect resolveAuthContext behavior in Auth when role mismatches occur
• confirm the live route in src/index.js points at the intended controller method
• validate D1-backed service and permission rows before treating the issue as a UI bug

Change Log / Verification

• Verified against the current Auth controller and middleware shape on 2026-03-29
• This page is the canonical internal starting point for auth-related debugging