# DDB API Key - Step-by-Step Registration Guide

## 🎯 Goal
Get your Deutsche Digitale Bibliothek (DDB) API key to harvest Archivportal-D data.

---

## 📍 Exact Steps to Get API Key

### Step 1: Register for Account (5 minutes)

1. **Visit DDB Portal**:
   ```
   https://www.deutsche-digitale-bibliothek.de/
   ```

2. **Click "Anmelden" (Login)** button:
   - Located in top-right corner of page
   - Blue button that says "Anmelden"

3. **On login modal, click "Registrieren" (Register)**:
   - Should see registration form
   - Or navigate directly to: https://www.deutsche-digitale-bibliothek.de/user/register

4. **Fill registration form**:
   - Email address
   - Username
   - Password (minimum requirements shown on form)
   - Accept terms of service
   
5. **Submit registration**

6. **Verify email**:
   - Check inbox for verification email from DDB
   - Click verification link
   - ⏱️ Email usually arrives within 1-2 minutes

---

### Step 2: Log In (1 minute)

1. **Go back to DDB portal**:
   ```
   https://www.deutsche-digitale-bibliothek.de/
   ```

2. **Click "Anmelden" button** (top right)

3. **Enter credentials**:
   - Username or email
   - Password

4. **Click login button**

---

### Step 3: Navigate to API Key Page (1 minute)

**Option A - Direct URL** (fastest):
```
https://www.deutsche-digitale-bibliothek.de/user/apikey
```

**Option B - Via Menu** (if direct URL doesn't work):
1. After logging in, look for account menu (usually your username in top-right)
2. Click on your account name
3. Select "Meine DDB" (My DDB)
4. Look for "API" or "API-Schlüssel" (API Key) section

---

### Step 4: Generate API Key (1 minute)

On the API key page (`/user/apikey`):

1. **Look for button**: "API-Schlüssel erstellen" or "Generate API Key"

2. **Click the button**

3. **Copy the key**:
   - Key will be a long string like: `ddb_abc123xyz456def789...`
   - ⚠️ **IMPORTANT**: Copy it immediately and save it securely
   - DDB may not show it again after you leave the page

4. **Save the key**:
   - Password manager (recommended)
   - Or secure note file
   - ❌ Do NOT commit to git (it's in `.gitignore`)

---

## 🔧 Add Key to Harvester Script

Once you have your API key:

```bash
cd /Users/kempersc/apps/glam
nano scripts/scrapers/harvest_archivportal_d_api.py
```

**Edit line 21**:

```python
# BEFORE (line 21):
API_KEY = "YOUR_API_KEY_HERE"

# AFTER (line 21):
API_KEY = "ddb_abc123xyz456def789..."  # Your actual key
```

Save and exit (Ctrl+O, Enter, Ctrl+X in nano).

---

## ✅ Verify API Key Works (Optional Test)

Test that your key is valid:

```bash
curl -H "Authorization: Bearer YOUR_KEY_HERE" \
  "https://api.deutsche-digitale-bibliothek.de/search?query=*&rows=1"
```

**Expected response**: JSON with search results  
**Error 401**: Key is invalid or expired  
**Error 403**: Key doesn't have permissions

---

## 🚨 Troubleshooting

### Issue: Can't Find "Registrieren" Button

**Solution**: Look for these German words on the login page:
- "Neu registrieren" (Register new)
- "Konto erstellen" (Create account)
- "Registrierung" (Registration)

### Issue: Verification Email Doesn't Arrive

**Solutions**:
- Check spam/junk folder
- Wait 5-10 minutes (email servers can be slow)
- Request new verification email (usually button on login page)
- Contact DDB support: https://www.deutsche-digitale-bibliothek.de/contact

### Issue: API Key Page is Empty

**Solutions**:
- Make sure you're logged in (check top-right for your username)
- Try direct URL: https://www.deutsche-digitale-bibliothek.de/user/apikey
- Clear browser cache and cookies
- Try different browser

### Issue: Can't Generate API Key

**Possible reasons**:
- Account not verified yet (check email)
- Need to accept additional API terms of service (look for checkbox)
- API limit reached (unlikely for new accounts)

**Solution**: Contact DDB support with screenshot

---

## 📚 Additional Resources

- **DDB API Documentation**: https://api.deutsche-digitale-bibliothek.de/
- **DDB Contact Form**: https://www.deutsche-digitale-bibliothek.de/contact
- **DDB User Guide** (German): https://www.deutsche-digitale-bibliothek.de/content/nutzungshinweise

---

## 🔒 Security Notes

- ✅ **DO**: Store key in password manager or secure note
- ✅ **DO**: Keep key private (it's tied to your account)
- ✅ **DO**: Add to `.gitignore` before committing code
- ❌ **DON'T**: Share key publicly
- ❌ **DON'T**: Commit key to git repository
- ❌ **DON'T**: Post key in forums/chat (even for help)

---

## ⏱️ Total Time: ~10 Minutes

- Step 1 (Register): 5 minutes
- Step 2 (Log in): 1 minute
- Step 3 (Navigate): 1 minute
- Step 4 (Generate key): 1 minute
- Configure script: 2 minutes

---

## ✨ After You Have the Key

Continue with the execution guide:

```bash
cd /Users/kempersc/apps/glam

# 1. Run API harvest (1-2 hours)
python3 scripts/scrapers/harvest_archivportal_d_api.py

# 2. Cross-reference with ISIL (1 hour)
python3 scripts/scrapers/merge_archivportal_isil.py

# 3. Create unified dataset (1 hour)
python3 scripts/scrapers/create_german_unified_dataset.py
```

See `EXECUTION_GUIDE.md` for complete instructions.

---

**Last Updated**: November 19, 2025  
**Verified**: Registration flow active, API key page exists at `/user/apikey`