feat: require org membership to create sessions

Gate session creation behind ml-agent-explorers org membership.
Shows a join step on the welcome screen for users not yet in the org.

backend/dependencies.py

@@ -22,6 +22,9 @@ AUTH_ENABLED = bool(os.environ.get("OAUTH_CLIENT_ID", ""))
 _token_cache: dict[str, tuple[dict[str, Any], float]] = {}
 TOKEN_CACHE_TTL = 300  # 5 minutes
 
+# Org membership cache: key -> expiry_time (only caches positive results)
+_org_member_cache: dict[str, float] = {}
+
 DEV_USER: dict[str, Any] = {
     "user_id": "dev",
     "username": "dev",
@@ -80,6 +83,31 @@ async def _extract_user_from_token(token: str) -> dict[str, Any] | None:
     return None
 
 
+async def check_org_membership(token: str, org_name: str) -> bool:
+    """Check if the token owner belongs to an HF org. Only caches positive results."""
+    now = time.time()
+    key = token + org_name
+    cached = _org_member_cache.get(key)
+    if cached and cached > now:
+        return True
+
+    async with httpx.AsyncClient(timeout=10.0) as client:
+        try:
+            resp = await client.get(
+                f"{OPENID_PROVIDER_URL}/api/whoami-v2",
+                headers={"Authorization": f"Bearer {token}"},
+            )
+            if resp.status_code != 200:
+                return False
+            orgs = {o.get("name") for o in resp.json().get("orgs", [])}
+            if org_name in orgs:
+                _org_member_cache[key] = now + TOKEN_CACHE_TTL
+                return True
+            return False
+        except httpx.HTTPError:
+            return False
+
+
 async def get_current_user(request: Request) -> dict[str, Any]:
     """FastAPI dependency: extract and validate the current user.
 

backend/routes/agent.py

@@ -8,7 +8,7 @@ import logging
 import os
 from typing import Any
 
-from dependencies import get_current_user, get_ws_user
+from dependencies import AUTH_ENABLED, check_org_membership, get_current_user, get_ws_user
 from fastapi import (
     APIRouter,
     Depends,
@@ -35,6 +35,9 @@ logger = logging.getLogger(__name__)
 
 router = APIRouter(prefix="/api", tags=["agent"])
 
+REQUIRED_ORG = "ml-agent-explorers"
+ORG_JOIN_URL = "https://huggingface.co/organizations/ml-agent-explorers/share/GzPMJUivoFPlfkvFtIqEouZKSytatKQSZT"
+
 AVAILABLE_MODELS = [
     {
         "id": "anthropic/claude-opus-4-6",
@@ -214,6 +217,14 @@ async def create_session(
     if not hf_token:
         hf_token = request.cookies.get("hf_access_token")
 
+    # Gate access behind org membership
+    if AUTH_ENABLED and hf_token:
+        if not await check_org_membership(hf_token, REQUIRED_ORG):
+            raise HTTPException(
+                status_code=403,
+                detail={"error": "org_required", "join_url": ORG_JOIN_URL},
+            )
+
     try:
         session_id = await session_manager.create_session(
             user_id=user["user_id"], hf_token=hf_token

frontend/src/components/WelcomeScreen/WelcomeScreen.tsx

@@ -7,6 +7,7 @@ import {
   Alert,
 } from '@mui/material';
 import OpenInNewIcon from '@mui/icons-material/OpenInNew';
+import GroupAddIcon from '@mui/icons-material/GroupAdd';
 import { useSessionStore } from '@/store/sessionStore';
 import { useAgentStore } from '@/store/agentStore';
 import { apiFetch } from '@/utils/api';
@@ -15,34 +16,34 @@ import { isInIframe, triggerLogin } from '@/hooks/useAuth';
 /** HF brand orange */
 const HF_ORANGE = '#FF9D00';
 
+interface OrgGate {
+  joinUrl: string;
+}
+
 export default function WelcomeScreen() {
   const { createSession } = useSessionStore();
   const { setPlan, clearPanel, user } = useAgentStore();
   const [isCreating, setIsCreating] = useState(false);
   const [error, setError] = useState<string | null>(null);
+  const [orgGate, setOrgGate] = useState<OrgGate | null>(null);
 
   const inIframe = isInIframe();
   const isAuthenticated = user?.authenticated;
   const isDevUser = user?.username === 'dev';
 
-  const handleStart = useCallback(async () => {
-    if (isCreating) return;
-
-    // Not authenticated and not dev → need to login
-    if (!isAuthenticated && !isDevUser) {
-      // In iframe: can't redirect (cookies blocked) — user needs to open in new tab
-      // This shouldn't happen because we show a different button in iframe
-      // But just in case:
-      if (inIframe) return;
-      triggerLogin();
-      return;
-    }
-
+  const tryCreateSession = useCallback(async () => {
     setIsCreating(true);
     setError(null);
 
     try {
       const response = await apiFetch('/api/session', { method: 'POST' });
+      if (response.status === 403) {
+        const data = await response.json();
+        if (data.detail?.error === 'org_required') {
+          setOrgGate({ joinUrl: data.detail.join_url });
+          return;
+        }
+      }
       if (response.status === 503) {
         const data = await response.json();
         setError(data.detail || 'Server is at capacity. Please try again later.');
@@ -57,6 +58,7 @@ export default function WelcomeScreen() {
         return;
       }
       const data = await response.json();
+      setOrgGate(null);
       createSession(data.session_id);
       setPlan([]);
       clearPanel();
@@ -65,7 +67,19 @@ export default function WelcomeScreen() {
     } finally {
       setIsCreating(false);
     }
-  }, [isCreating, createSession, setPlan, clearPanel, isAuthenticated, isDevUser, inIframe]);
+  }, [createSession, setPlan, clearPanel]);
+
+  const handleStart = useCallback(async () => {
+    if (isCreating) return;
+
+    if (!isAuthenticated && !isDevUser) {
+      if (inIframe) return;
+      triggerLogin();
+      return;
+    }
+
+    await tryCreateSession();
+  }, [isCreating, isAuthenticated, isDevUser, inIframe, tryCreateSession]);
 
   // Build the direct Space URL for the "open in new tab" link
   const spaceHost = typeof window !== 'undefined'
@@ -129,8 +143,67 @@ export default function WelcomeScreen() {
         and explores <strong>datasets</strong> — all through natural conversation.
       </Typography>
 
-      {/* Action button — depends on context */}
-      {inIframe && !isAuthenticated && !isDevUser ? (
+      {/* Action area — depends on context */}
+      {orgGate ? (
+        // Authenticated but not in org → join step
+        <Box sx={{ display: 'flex', flexDirection: 'column', alignItems: 'center', gap: 2, maxWidth: 480, px: 2 }}>
+          <Typography
+            variant="body2"
+            sx={{
+              color: 'var(--muted-text)',
+              textAlign: 'center',
+              lineHeight: 1.7,
+              fontSize: '0.88rem',
+              '& strong': { color: 'var(--text)', fontWeight: 600 },
+            }}
+          >
+            Under the hood, this agent uses GPUs, inference APIs, and other paid Hub goodies — but we made them all free for you.
+            Just join <strong>ML Agent Explorers</strong> and you're in!
+          </Typography>
+          <Button
+            variant="contained"
+            size="large"
+            component="a"
+            href={orgGate.joinUrl}
+            target="_blank"
+            rel="noopener noreferrer"
+            startIcon={<GroupAddIcon />}
+            sx={{
+              px: 5,
+              py: 1.5,
+              fontSize: '1rem',
+              fontWeight: 700,
+              textTransform: 'none',
+              borderRadius: '12px',
+              bgcolor: HF_ORANGE,
+              color: '#000',
+              boxShadow: '0 4px 24px rgba(255, 157, 0, 0.3)',
+              textDecoration: 'none',
+              '&:hover': {
+                bgcolor: '#FFB340',
+                boxShadow: '0 6px 32px rgba(255, 157, 0, 0.45)',
+              },
+            }}
+          >
+            Join ML Agent Explorers
+          </Button>
+          <Button
+            variant="text"
+            size="small"
+            onClick={tryCreateSession}
+            disabled={isCreating}
+            startIcon={isCreating ? <CircularProgress size={16} color="inherit" /> : null}
+            sx={{
+              color: 'var(--muted-text)',
+              textTransform: 'none',
+              fontSize: '0.85rem',
+              '&:hover': { color: 'var(--text)' },
+            }}
+          >
+            {isCreating ? 'Checking...' : "I've joined — let's go"}
+          </Button>
+        </Box>
+      ) : inIframe && !isAuthenticated && !isDevUser ? (
         // In iframe + not logged in → link to open Space directly
         <Button
           variant="contained"