quasar/docs/API_KEYS.md

Obtaining API Keys

This guide explains how to get credentials for each metadata service.

IGDB (Internet Game Database)

IGDB uses OAuth 2.0 via Twitch. Steps:

1. Go to Twitch Developer Console
2. Sign in with your Twitch account (create one if needed)
3. Click "Create Application"
   • Name: "Quasar" (or your app name)
   • Category: Select relevant category
   • Accept terms, click Create
4. You'll see:
   • Client ID — Copy this
   • Click "New Secret" to generate Client Secret — Copy this
5. Go to Settings → OAuth Redirect URLs
   • Add: http://localhost:3000/oauth/callback (development)
   • For production: https://yourdomain.com/oauth/callback
6. In your .env file:

   IGDB_CLIENT_ID=your_client_id
   IGDB_CLIENT_SECRET=your_client_secret
   

7. Start Quasar, it will use IGDB automatically

Rate Limit: 4 requests/second

RAWG (Rawg.io)

RAWG has a simpler API Key approach:

1. Go to RAWG Settings
2. Sign up if needed, then login
3. Find "API Key" section
4. Click "Create new key" (if needed) or copy existing key
5. In your .env file:

   RAWG_API_KEY=your_api_key_here
   

6. Start Quasar

Rate Limit: 20 requests/second (free tier)

Note: RAWG requires attribution in UI (include "Powered by RAWG" somewhere visible)

TheGamesDB (thegamesdb.net)

TheGamesDB uses a simple API Key:

1. Go to TheGamesDB API
2. Find "API Key" section (free registration required)
3. Register or login
4. Copy your API key
5. In your .env file:

   THEGAMESDB_API_KEY=your_api_key_here
   

6. Start Quasar

Rate Limit: 1 request/second (free tier)

Testing Without Real Keys

For development/testing:

• Leave API keys as your_*_here in .env.local
• Quasar will gracefully degrade and show limited metadata
• Frontend will still work with manual game entry

Production Deployment

For production:

1. Generate new keys on each service (don't reuse dev keys)
2. Store keys in Gitea Secrets (for automated CI/CD pipelines)
3. Or use environment variables on your hosting provider
4. Rotate keys every 3 months
5. Monitor rate limits in service dashboards

Gitea Actions CI/CD Setup

To enable automated testing with API keys in Gitea Actions:

1. Store Secrets in Gitea

Navigate to your repository settings:

https://your-gitea-instance/your-org/quasar/settings/secrets/actions

Add these secrets:

• IGDB_CLIENT_ID (from Twitch Developer Console)
• IGDB_CLIENT_SECRET (from Twitch Developer Console)
• RAWG_API_KEY (from RAWG settings)
• THEGAMESDB_API_KEY (from TheGamesDB API)

2. Workflow Configuration

The .gitea/workflows/ci.yml workflow automatically:

• ✅ Installs dependencies
• ✅ Runs linting checks
• ✅ Executes backend tests (Vitest)
• ✅ Executes frontend tests (Vitest)
• ✅ Starts backend + frontend servers
• ✅ Runs E2E tests (Playwright) with real metadata APIs
• ✅ Uploads test reports on failure

3. Testing Flow

1. Push code to main or develop
2. Gitea Actions picks up the .gitea/workflows/ci.yml
3. Secrets are injected as IGDB_CLIENT_ID, IGDB_CLIENT_SECRET, RAWG_API_KEY, THEGAMESDB_API_KEY
4. E2E tests fetch real metadata from APIs (using injected secrets)
5. Build fails if any test fails (prevents broken code)

4. Local Development

For local testing, use .env.local:

IGDB_CLIENT_ID=your_local_id
IGDB_CLIENT_SECRET=your_local_secret
RAWG_API_KEY=your_local_key
THEGAMESDB_API_KEY=your_local_key

Note: CI/CD uses Gitea Secrets (not .env files), so never commit real credentials.

Troubleshooting

"IGDB_CLIENT_ID not found" → Check .env file exists and has correct format

"429 Too Many Requests" → Rate limit exceeded, wait and retry

"Invalid API Key" → Copy key exactly (no spaces), verify it's active on service website