# 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](https://dev.twitch.tv/console/apps)
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](https://rawg.io/settings/account)
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](https://thegamesdb.net/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`:

```bash
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