TopoloAuth

Central authentication and identity management for the Topolo platform.

Overview

TopoloAuth provides centralized authentication, authorization, and identity management across all Topolo applications. It implements:

Single Sign-On (SSO) across all apps
Organization management
Role-based access control
Multiple authentication methods
OAuth 2.0 provider for third-party apps

Authentication Methods

Email/Password

Traditional email and password authentication with:

Secure password hashing (Argon2)
Password strength requirements
Account lockout protection

OAuth 2.0 integration with:

Google
Microsoft
GitHub
Apple (coming soon)

Passkeys/WebAuthn

Passwordless authentication using:

Biometric authentication
Hardware security keys
Platform authenticators

Multi-Factor Authentication (MFA)

Additional security with:

TOTP (authenticator apps)
SMS codes
Email codes

Organization Model

Organization
├── Members
│   ├── Owner
│   ├── Admins
│   └── Members
├── Services (enabled apps)
├── Settings
│   ├── SSO Configuration
│   ├── Security Policies
│   └── Branding
└── Billing

For Developers

Using TopoloAuth

JavaScript/TypeScript

npm install @topolo/auth-client

import { TopoloAuth } from '@topolo/auth-client';

const auth = new TopoloAuth({
  domain: 'auth.topolo.io',
  clientId: 'your_client_id',
});

// Login
await auth.loginWithRedirect();

// Get user
const user = await auth.getUser();

// Get token for API calls
const token = await auth.getToken();

Flutter/Dart

dependencies:
  topolo_auth_flutter: ^1.0.0

import 'package:topolo_auth_flutter/topolo_auth_flutter.dart';

final auth = TopoloAuth(
  domain: 'auth.topolo.io',
  clientId: 'your_client_id',
);

// Login
await auth.loginWithBrowser();

// Get user
final user = await auth.getUser();

Protecting Routes

Express.js Middleware

import { authMiddleware } from '@topolo/auth-middleware';

app.use('/api', authMiddleware({
  issuer: 'https://auth.topolo.io',
}));

app.get('/api/protected', (req, res) => {
  const user = req.auth.user;
  res.json({ user });
});

Cloudflare Workers

import { verifyToken } from '@topolo/auth-middleware';

export default {
  async fetch(request: Request, env: Env) {
    const auth = await verifyToken(request, env.JWT_SECRET);

    if (!auth) {
      return new Response('Unauthorized', { status: 401 });
    }

    // auth.userId, auth.organizationId available
  }
};

JWT Structure

Tokens issued by TopoloAuth contain:

{
  "sub": "user_abc123",
  "org_id": "org_xyz789",
  "email": "user@example.com",
  "name": "John Doe",
  "permissions": ["read", "write"],
  "iat": 1706054400,
  "exp": 1706140800,
  "iss": "https://auth.topolo.io"
}

OAuth 2.0 Provider

TopoloAuth can be an OAuth provider for third-party applications:

Authorization Code Flow

Redirect user to authorize:

https://auth.topolo.io/oauth/authorize?
  client_id=YOUR_CLIENT_ID&
  redirect_uri=YOUR_CALLBACK&
  response_type=code&
  scope=openid profile email

Exchange code for tokens:

const response = await fetch('https://auth.topolo.io/oauth/token', {
  method: 'POST',
  body: JSON.stringify({
    grant_type: 'authorization_code',
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_SECRET',
    code: authCode,
    redirect_uri: 'YOUR_CALLBACK',
  }),
});

Available Scopes

Scope	Description
`openid`	Basic authentication
`profile`	User name and avatar
`email`	User email address
`org`	Organization membership
`nexus:ai`	AI completion access
`nexus:usage:read`	Read AI usage stats

API Reference

Endpoint	Method	Description
`/oauth/authorize`	GET	Start OAuth flow
`/oauth/token`	POST	Exchange code for tokens
`/oauth/userinfo`	GET	Get user info
`/api/users/me`	GET	Get current user
`/api/organizations`	GET	List user’s orgs