aethex-forge/docs/DISCORD-OAUTH-SETUP-VERIFICATION.md

Discord OAuth Setup Verification Checklist

🔴 CRITICAL: OAuth Redirect URI Registration

This is the most common cause of session loss during Discord linking.

Step 1: Open Discord Developer Portal

1. Go to: https://discord.com/developers/applications
2. Find and click: AeThex application
3. Left sidebar, click: OAuth2
4. Find the section: REDIRECT URLS or REDIRECTS

Step 2: Verify Redirect URI is Registered

You must have this exact URL registered:

https://aethex.dev/api/discord/oauth/callback

If you're using a different domain (like localhost for testing):

http://localhost:5173/api/discord/oauth/callback

Step 3: Add Missing Redirect URI (If Needed)

If the URL is NOT listed:

1. Click: Add Redirect button
2. Paste the correct URL:

   https://aethex.dev/api/discord/oauth/callback
   

3. Click: Save Changes
4. Wait - changes may take 1-2 minutes to propagate

⚠️ IMPORTANT: The redirect URI must match EXACTLY:

• Correct: https://aethex.dev/api/discord/oauth/callback
• Wrong: https://aethex.dev/api/discord/callback (missing /oauth)
• Wrong: aethex.dev/api/discord/oauth/callback (missing https://)
• Wrong: https://aethex.dev/api/discord/oauth/callback/ (trailing slash)

---

🟢 TESTING THE DISCORD LINKING FLOWS

After verifying the redirect URI, test both flows:

Test Flow 1: Discord /verify Command

1. In Discord, type: /verify
2. Click the link button or copy the code
3. Browser opens: https://aethex.dev/discord-verify?code=XXXXXX
4. Page auto-submits and links your account
5. You should see: ✅ Success message
6. Redirects to: /dashboard?tab=connections (FIXED)
7. You should see Discord in your connections list

If it redirects to /profile/settings instead:

• This has been FIXED in the code update

If it shows an error:

• Check the error message in the browser console
• Note: Session may be lost if redirect URI not registered

---

Test Flow 2: Dashboard "Link Discord" Button

This is the flow that had session loss issues.

1. Go to: /dashboard?tab=connections
2. Click: Link Discord button
3. You'll be redirected to Discord OAuth
4. Click: Authorize on Discord
5. Discord redirects back to your app
6. EXPECTED: You should be redirected to /dashboard?tab=connections
7. EXPECTED: You should still be logged in
8. EXPECTED: Discord should appear in your connections

If you're redirected to /login instead:

• Session was lost during OAuth callback
• Cause: Redirect URI not registered in Discord Dev Portal
• Solution: Follow Step 1-3 above to add the redirect URI
• Then: Try the flow again

If you see an error about session being lost:

• This means the backend detected missing session cookies
• Check the browser console for error details
• The error message now tells you to verify Discord Dev Portal settings

---

🔵 ENVIRONMENT VARIABLES CHECKLIST

Verify these are set correctly:

Frontend (code/.env or deployment platform)

• VITE_API_BASE is set to your API domain

  VITE_API_BASE=https://aethex.dev
  

  (Or your actual deployment domain)

• VITE_SUPABASE_URL is correct

  VITE_SUPABASE_URL=https://kmdeisowhtsalsekkzqd.supabase.co
  

• VITE_SUPABASE_ANON_KEY is set

Backend/Server (environment variables)

• DISCORD_CLIENT_ID is set

  DISCORD_CLIENT_ID=578971245454950421
  

• DISCORD_CLIENT_SECRET is set (production)

  DISCORD_CLIENT_SECRET=JKlilGzcTWgfmt2wEqiHO8wpCel5VEji
  

  ⚠️ NOTE: This is sensitive - only set in production, not in code

• VITE_SUPABASE_URL is set on backend

  VITE_SUPABASE_URL=https://kmdeisowhtsalsekkzqd.supabase.co
  

• SUPABASE_SERVICE_ROLE is set

  SUPABASE_SERVICE_ROLE=eyJhbGciOiJIUzI1NiIs...
  

  ⚠️ CRITICAL: Never commit this to git

---

🟡 COMMON ISSUES & SOLUTIONS

Issue 1: "Session Lost" Error After Discord OAuth

Cause: Redirect URI not registered in Discord Dev Portal

Solution:

1. Open Discord Developer Portal
2. Go to OAuth2 → Redirects
3. Verify https://aethex.dev/api/discord/oauth/callback is listed
4. If not listed, add it and save
5. Try the linking flow again (may need to clear browser cache first)

---

Issue 2: Discord Link Disappears After Page Reload

Cause: Linking succeeded but auth state not refreshed

Solution:

1. Verify the discord_links table in Supabase has the record
   • Go to: https://app.supabase.com/project/kmdeisowhtsalsekkzqd
   • Find table: discord_links
   • Check if your discord_id and user_id are recorded
2. If record exists but not showing in UI:
   • Reload the page or go to /dashboard
   • The UI should refresh and show Discord connection
3. If record doesn't exist:
   • The linking failed silently
   • Check browser console for errors
   • Try the /verify flow instead

---

Issue 3: Wrong Redirect Page After /verify Command

Old Problem: Redirected to /profile/settings

Solution: ✅ FIXED in code

• The code now redirects to /dashboard?tab=connections
• If you're still seeing /profile/settings:
  • Clear browser cache (Ctrl+Shift+Delete)
  • Deploy the latest code changes

---

Issue 4: "Already Linked" Error in /verify Command

Cause: Discord account already linked to an AeThex account

Solutions:

• Option A: Use a different Discord account
• Option B: Contact admin to unlink the Discord account from the other AeThex account
• Option C: If it's your old account, use \unlink command to disconnect it, then /verify again

---

🟣 DEBUGGING STEPS

If something isn't working, follow these steps:

Step 1: Check Browser Console

1. Open Discord or your app
2. Press F12 (DevTools)
3. Go to Console tab
4. Look for messages starting with [Discord OAuth] or [Discord Activity]
5. Take a screenshot of any error messages

Step 2: Check Network Tab

1. In DevTools, go to Network tab
2. Perform the Discord linking flow
3. Look for a request to /api/discord/oauth/callback?code=...
4. Click on it and check:
   • Request Headers → Cookie (should have sb-access-token)
   • Response Headers → Set-Cookie (should have new tokens)
   • Status → Should be 302 (redirect)

Step 3: Check Supabase

1. Go to: https://app.supabase.com/project/kmdeisowhtsalsekkzqd
2. Find table: discord_links
3. Look for your discord_id (check if record exists)
4. If record exists but UI doesn't show it:
   • Reload the page
   • Or manually call refreshAuthState()
5. If record doesn't exist:
   • Linking never succeeded
   • Check the Network tab request/response above

Step 4: Check Discord Dev Portal

1. Go to: https://discord.com/developers/applications/578971245454950421
2. Click: OAuth2
3. Scroll to: REDIRECT URLS
4. Verify: https://aethex.dev/api/discord/oauth/callback is listed
5. If missing:
   • Add it
   • Save
   • Wait 1-2 minutes
   • Try linking again

---

✅ Verification Checklist

When everything is working correctly, you should see:

• Discord /verify command generates a code
• Clicking the link shows verification page
• Code auto-submits and succeeds
• Redirects to /dashboard?tab=connections (not /profile/settings)
• Discord appears in connections list
• Clicking "Link Discord" button on dashboard works
• User redirected to /dashboard?tab=connections after Discord OAuth
• User remains logged in after Discord OAuth
• Discord appears in connections list immediately
• Page reload doesn't lose Discord connection
• Running /verify again shows "Already Linked" message

When all items are checked, your Discord linking is fully functional! 🎉

---

Related Documentation

• DISCORD-LINKING-FLOW-ANALYSIS.md - Flow diagrams and architecture
• DISCORD-ACTIVITY-SETUP.md - Discord Activity/slash commands setup
• DISCORD-ADMIN-COMMANDS-REGISTRATION.md - Bot command registration