API Keys Guide

Complete guide for obtaining all API keys needed for Egg Shen Bot.

Overview

Service	Required	Free Tier	Registration	Approval Time
Discord Bot	✅ Yes	Yes	Discord Portal	Instant
TMDB	✅ Yes	Yes	TMDB	1-2 minutes
OMDB	⭕ Optional	1000/day	OMDB	Instant
Trakt	⭕ Optional	Yes	Trakt	Instant
RAWG	⭕ Optional	20,000/month	RAWG	Instant
BoardGameGeek	⭕ Optional	Yes	BGG XML API	Instant

---

Discord Bot Token

Purpose: Required for bot to connect to Discord
Features Enabled: All bot functionality
Free Tier: Unlimited for self-hosted bots

Step-by-Step Instructions

1. Go to Discord Developer Portal

   • Visit https://discord.com/developers/applications
   • Log in with your Discord account

2. Create New Application

   • Click "New Application" button
   • Enter a name for your bot (e.g., "Egg Shen Bot")
   • Accept Discord's Terms of Service
   • Click "Create"

3. Configure Bot

   • Click "Bot" in the left sidebar
   • Click "Add Bot" (if not already added)
   • Confirm by clicking "Yes, do it!"

4. Enable Intents

   • Scroll down to "Privileged Gateway Intents"
   • Enable "Server Members Intent" ✅
   • Enable "Message Content Intent" ✅
   • Click "Save Changes"

5. Get Bot Token

   • Under "TOKEN" section, click "Reset Token"
   • Copy the token that appears
   • ⚠️ IMPORTANT: Never share this token publicly!
   • Add to .env file as DISCORD_TOKEN

6. Get Client ID

   • Click "General Information" in left sidebar
   • Copy the "APPLICATION ID"
   • Add to .env file as DISCORD_CLIENT_ID

---

TMDB API Key

Purpose: Movie and TV show data (required for core features)
Features Enabled: /movie, /tv, /episode, /random, /similar, watch history
Free Tier: Unlimited requests

Step-by-Step Instructions

1. Create TMDB Account

   • Visit https://www.themoviedb.org/signup
   • Sign up with email or social login
   • Verify your email address

2. Request API Key

   • Go to your account settings: https://www.themoviedb.org/settings/api
   • Click "Create" under "Request an API Key"
   • Select "Developer"
   • Accept the Terms of Use

3. Fill Out Application

   • Application Name: "Egg Shen Discord Bot" (or your name)
   • Application URL: Your website or https://github.com/r3volution11/Egg-Shen-Bot
   • Application Summary: "Discord bot for searching movies and TV shows"
   • Submit the form

4. Get API Key

   • Your API key (v3 auth) will be displayed immediately
   • Copy the "API Key" (not the API Read Access Token)
   • Add to .env file as TMDB_API_KEY

Rate Limits: None officially documented

---

OMDB API Key

Purpose: IMDb and Rotten Tomatoes ratings
Features Enabled: Enhanced rating displays
Free Tier: 1,000 requests per day

Step-by-Step Instructions

1. Request API Key

   • Visit http://www.omdbapi.com/apikey.aspx
   • Select "FREE! (1,000 daily limit)"
   • Enter your email address
   • Enter your first and last name
   • Click "Submit"

2. Verify Email

   • Check your email inbox
   • Click the activation link in the email from OMDb API
   • This will activate your API key

3. Get API Key

   • After clicking activation link, your API key is displayed
   • Copy the API key
   • Add to .env file as OMDB_API_KEY

Rate Limits: 1,000 requests per day

Upgrade Options:

• $1/month: 100,000 requests/month
• $5/month: 500,000 requests/month

---

Trakt Client ID

Purpose: Community ratings and watch statistics
Features Enabled: Trakt rating display in embeds
Free Tier: Unlimited

Step-by-Step Instructions

1. Create Trakt Account

   • Visit https://trakt.tv/auth/join
   • Sign up with email or social login

2. Create OAuth Application

   • Go to https://trakt.tv/oauth/applications
   • Click "New Application"

3. Fill Out Application Form

   • Name: "Egg Shen Discord Bot"
   • Description: "Discord bot for searching movies and TV shows"
   • Redirect URI: urn:ietf:wg:oauth:2.0:oob
   • Permissions: Leave defaults (only need public data)
   • Check "I have read the API Terms"
   • Click "Save App"

4. Get Client ID

   • Your new app will appear in the applications list
   • Click on your app name to view details
   • Copy the "Client ID"
   • Add to .env file as TRAKT_CLIENT_ID

Rate Limits: 1,000 requests per 5 minutes

---

RAWG API Key

Purpose: Video game data and ratings
Features Enabled: /game, /random game, /similar (games)
Free Tier: 20,000 requests per month

Step-by-Step Instructions

1. Create RAWG Account

   • Visit https://rawg.io/
   • Click "Sign Up" in top right
   • Create account with email or social login

2. Get API Key

   • Go to https://rawg.io/apidocs
   • Scroll down to "Get an API key" section
   • Your API key is automatically generated and displayed
   • Click "Copy" to copy your key
   • Add to .env file as RAWG_API_KEY

Rate Limits:

• Free tier: 20,000 requests/month
• Max 4 requests per second

Note: If commands aren't configured, /game won't appear in Discord.

---

BoardGameGeek Client ID

Purpose: Board game data and ratings
Features Enabled: /boardgame, /random boardgame, /similar (board games)
Free Tier: Yes (rate limits apply)

Step-by-Step Instructions

1. Create BGG Account

   • Visit https://boardgamegeek.com/
   • Click "Join" in top right
   • Create account with username and email

2. Read API Documentation

   • Visit https://boardgamegeek.com/wiki/page/BGG_XML_API2
   • Review the API terms and guidelines
   • No formal registration required for basic usage

3. Get API Credentials

   • For basic usage, BGG XML API2 doesn't require authentication
   • However, for better rate limits, you can request developer credentials
   • Contact BGG support at: https://boardgamegeek.com/contact
   • Request OAuth credentials for "Egg Shen Discord Bot"
   • They will provide you with a Client ID

4. Configure in Bot

   • Once you receive your Client ID from BGG support
   • Add to .env file as BGG_CLIENT_ID

Alternative (No Auth):

• If you don't have a Client ID yet, you can run the bot without it
• The /boardgame command won't be registered
• Basic API access still works but with lower rate limits

Rate Limits:

• Unauthenticated: ~2 requests per second
• With credentials: Higher limits (varies)

Note: BGG API approval can take 1-3 business days via email support.

---

Configuration File

Once you have all your API keys, add them to your .env file:

# Discord Configuration (Required)
DISCORD_TOKEN=your_discord_bot_token_here
DISCORD_CLIENT_ID=your_discord_client_id_here

# TMDB API (Required)
TMDB_API_KEY=your_tmdb_api_key_here

# Optional APIs
OMDB_API_KEY=your_omdb_api_key_here
TRAKT_CLIENT_ID=your_trakt_client_id_here
RAWG_API_KEY=your_rawg_api_key_here
BGG_CLIENT_ID=your_bgg_client_id_here

Security Best Practices

1. Never commit .env to version control

   • Already included in .gitignore
   • Contains sensitive credentials

2. Rotate tokens if exposed

   • If you accidentally share a token, regenerate it immediately
   • Discord: Reset token in Developer Portal
   • TMDB: Generate new key in API settings
   • Others: Contact support or regenerate

3. Use environment variables in production

   • On servers, set env vars directly (not .env file)
   • Example for PM2: pm2 start ecosystem.config.js --update-env

4. Monitor API usage

   • Check your API dashboards regularly
   • Set up alerts for rate limit warnings
   • Most services provide usage statistics

Troubleshooting

"Invalid API Key" Errors

• TMDB: Make sure you copied the API Key (v3), not the Read Access Token
• OMDB: Verify you clicked the email activation link
• Trakt: Use Client ID, not Client Secret
• RAWG: Key is shown on https://rawg.io/apidocs when logged in

Commands Not Appearing

• Run deployment: npm run deploy-commands or restart bot
• Check logs: Look for "Skipped command" messages indicating missing API keys
• Discord cache: Commands can take up to 1 hour to update globally (use guild ID for testing)

Rate Limit Errors

• OMDB Free Tier: 1,000/day - consider upgrading if hitting limits
• RAWG: 20,000/month - monitor usage in dashboard
• Trakt: 1,000 per 5 min - bot includes built-in retry logic

Still Having Issues?

• Check Installation Guide
• Review Getting Started
• Open an issue on GitHub