Authentication

Canopi uses Web3Auth for wallet and social sign-in, with an optional Auth0 hybrid mode to fix OAuth iframe caching on re-login.

Sign-in flow (overview)

User clicks Sign in
  → Web3Auth modal OR Auth0 popup (Mode 2)
  → getUserInfo()
  → POST /api/auth/web3auth
  → JWT stored in extension / embed session

All authenticated API calls:

Authorization: Bearer <jwt>

Mode 1 — Default Web3Auth modal

When: first login, or Auth0 not configured.

Providers: Google, Twitter, Apple, Discord, GitHub, Facebook, LinkedIn, Reddit, Twitch, email/SMS passwordless, MetaMask, WalletConnect, and other Web3Auth connectors.

Flow:

await web3auth.init();
await web3auth.connect();
const user = await web3auth.getUserInfo();
// POST /api/auth/web3auth with idToken

Limitation: Web3Auth iframe caching can lock users to the last OAuth provider after logout.

Mode 2 — Auth0 JWT (hybrid)

When: re-login after logout, Auth0 env vars configured, forceProviderPicker=true.

Flow:

await web3auth.init();
// Custom provider picker
await auth0.loginWithPopup({ connection: 'google-oauth2' });
const claims = await auth0.getIdTokenClaims();
await web3auth.connectTo('auth', { idToken: claims.__raw, authConnectionId });
// POST /api/auth/web3auth

Benefit: users can switch OAuth providers without clearing browser data.

Auth communities

Each OAuth provider or wallet type maps to an auth community — a shared namespace for presence, messages, and policy. Communities appear in the logo cloud and community picker.

Stats endpoint (public):

GET /api/auth-communities/stats

Supabase redirect URLs

If using Supabase-backed create flows, add redirect URLs in Supabase Dashboard → Authentication → URL Configuration:

• https://app.canopi.live/create
• https://app.canopi.live/embed/create.html

The redirect origin must match where the user started sign-in.

Environment variables (operators)

Set on the Express backend (canopi-prod):

AUTH0_DOMAIN=your-tenant.us.auth0.com
AUTH0_CLIENT_ID=your_client_id
W3A_AUTH0_CONNECTION_ID=your_connection_id

Without these, Mode 2 is disabled and all logins use Mode 1.

Related

• Getting started
• Logo cloud

Internal guides: docs/AUTH_MODES_REFERENCE.md, docs/HYBRID_AUTH_IMPLEMENTATION.md