Skip to content

DASHBOARD_SETUP.md

Latest commit

 

History

History
256 lines (200 loc) · 7.01 KB

DASHBOARD_SETUP.md

File metadata and controls

256 lines (200 loc) · 7.01 KB
Raw

DBAB API - Discord Dashboard Setup

This document guides you through setting up the DBAB API to support the Discord Bot Dashboard.

New Features Added

  • ✅ Discord OAuth2 Authentication
  • ✅ JWT Token-based Authentication
  • ✅ Guild Management (Server tracking)
  • ✅ Enhanced Appeal Management with Dashboard Routes
  • ✅ User Account Management

Database Changes

New tables have been added to support the dashboard:

users table

Stores Discord user information for dashboard access.

CREATE TABLE users (
  id VARCHAR PRIMARY KEY,
  discord_id VARCHAR UNIQUE NOT NULL,
  discord_tag VARCHAR NOT NULL,
  avatar VARCHAR,
  email VARCHAR,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);

guilds table

Stores guild (server) information linked to users.

CREATE TABLE guilds (
  id VARCHAR PRIMARY KEY,
  name VARCHAR NOT NULL,
  icon VARCHAR,
  owner_id VARCHAR NOT NULL,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);

Updated appeals table

Added new fields for dashboard support:

ALTER TABLE appeals ADD COLUMN status VARCHAR DEFAULT 'pending';
ALTER TABLE appeals ADD COLUMN response TEXT;
ALTER TABLE appeals ADD COLUMN userDiscordTag VARCHAR;

Configuration Setup

1. Update Your Config File

Edit ~/.dbab-config/dbab.json and add the following:

{
  "bot": {
    "token": "your_bot_token_here"
  },
  "mysql": {
    "host": "localhost",
    "user": "root",
    "password": "your_password",
    "database": "dbab_bot",
    "port": 3306
  },
  "discord": {
    "client_id": "YOUR_DISCORD_APP_ID",
    "client_secret": "YOUR_DISCORD_APP_SECRET",
    "redirect_uri": "http://localhost:5173/auth/discord/callback"
  },
  "jwt": {
    "secret": "your_very_secret_jwt_key_change_this"
  }
}

2. Get Discord OAuth Credentials

  1. Go to Discord Developer Portal
  2. Click "New Application" and name it
  3. Go to "OAuth2" → "General"
  4. Copy your Client ID and Client Secret
  5. Add Redirect URI: http://localhost:5173/auth/discord/callback
  6. Add them to your config file

3. Install Updated Dependencies

pip install -r requirements.txt

The following packages were added:

  • PyJWT==2.8.1 - For JWT token generation
  • aiohttp==3.9.1 - For Discord API requests
  • python-dotenv==1.0.0 - For environment variables

New API Endpoints

Authentication Endpoints

GET /auth/discord-auth-url

Returns the Discord OAuth authorization URL

  • Auth: None (Public)
  • Response: { "url": "https://discord.com/api/oauth2/authorize?..." }

POST /auth/discord-callback

Handles Discord OAuth callback

  • Auth: None (Public)
  • Body: { "code": "oauth_code" }
  • Response: { "token": "jwt_token", "user": {...} }

GET /auth/me

Get current authenticated user

  • Auth: Bearer token (JWT)
  • Response: User object with ID, Discord tag, avatar, etc.

Guild Endpoints

GET /guilds

Get all guilds owned by current user

  • Auth: Bearer token (JWT)
  • Response: Array of guild objects

GET /guilds/{guild_id}

Get specific guild details

  • Auth: Bearer token (JWT)
  • Response: Guild object

GET /guilds/{guild_id}/stats

Get appeal statistics for a guild

  • Auth: Bearer token (JWT)
  • Response: Stats object with total, pending, approved, denied counts

Dashboard Appeal Endpoints

GET /appeals

Get all appeals for user's guilds

  • Auth: Bearer token (JWT)
  • Response: Array of appeal objects

GET /appeals/{guild_id}

Get all appeals for a specific guild

  • Auth: Bearer token (JWT)
  • Response: Array of appeal objects

GET /appeals/detail/{appeal_id}

Get specific appeal details

  • Auth: Bearer token (JWT)
  • Response: Appeal object with all details

PUT /appeals/{appeal_id}

Update appeal status (approve/deny)

  • Auth: Bearer token (JWT)
  • Body: { "status": "approved|denied", "reason": "response_message" }
  • Response: Updated appeal object

Authentication Flow

  1. User clicks "Login with Discord" in dashboard
  2. API returns Discord auth URL via /auth/discord-auth-url
  3. User authorizes Discord app and is redirected to callback
  4. Dashboard exchanges code for token via /auth/discord-callback
  5. API validates code with Discord servers
  6. User data retrieved from Discord and stored in database
  7. JWT token generated and returned to dashboard
  8. Dashboard stores token in localStorage
  9. All subsequent requests include JWT in Authorization header

Authentication Headers

For authenticated requests, include the JWT token:

Authorization: Bearer <your_jwt_token_here>

Troubleshooting

CORS Issues

If you get CORS errors, the API already has CORS configured for all origins. Clear browser cache and try again.

Discord OAuth Errors

  • Verify Client ID and Secret are correct
  • Check that redirect URI exactly matches config and Discord settings
  • Ensure redirect_uri starts with http:// (not https:// for localhost)

Database Errors

Run these migrations to ensure tables exist:

-- Create users table if missing
CREATE TABLE IF NOT EXISTS users (
  id VARCHAR(255) PRIMARY KEY,
  discord_id VARCHAR(255) UNIQUE NOT NULL,
  discord_tag VARCHAR(255) NOT NULL,
  avatar VARCHAR(255),
  email VARCHAR(255),
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);

-- Create guilds table if missing
CREATE TABLE IF NOT EXISTS guilds (
  id VARCHAR(255) PRIMARY KEY,
  name VARCHAR(255) NOT NULL,
  icon VARCHAR(255),
  owner_id VARCHAR(255) NOT NULL,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);

-- Add missing columns to appeals
ALTER TABLE appeals ADD COLUMN IF NOT EXISTS status VARCHAR(50) DEFAULT 'pending';
ALTER TABLE appeals ADD COLUMN IF NOT EXISTS response TEXT;
ALTER TABLE appeals ADD COLUMN IF NOT EXISTS userDiscordTag VARCHAR(255);

Token Validation Errors

  • Clear localStorage in the dashboard (DevTools → Application → Storage)
  • Re-login through Discord OAuth
  • Ensure JWT secret in config is consistent

Running the API

python main.py

The API will start on http://localhost:3000 and the dashboard on http://localhost:5173.

Security Notes

⚠️ Important:

  • Change the JWT secret in production (jwt.secret in config)
  • Use HTTPS in production
  • Never commit config files with secrets
  • Keep Discord credentials private
  • Validate all user input on the backend

Integration with Dashboard

The DBAB Dashboard is pre-configured to work with these endpoints. To connect:

  1. Ensure API is running on http://localhost:3000
  2. Start dashboard: npm run dev in the DBAB-APP folder
  3. Visit http://localhost:5173
  4. Click "Login with Discord"

The dashboard will automatically handle all OAuth flows and token management.