homelab/compose/services/FreshRSS/API-AUTH-FIX.md

# FreshRSS iOS App Authentication Fix

## The Problem

You're getting "login failed" on your iOS RSS app, but the same credentials work on the website.

**Why:** iOS RSS apps use FreshRSS's **API**, which requires a separate **API password** - NOT your regular web login password.

## The Solution: Generate an API Password

### Step 1: Log into FreshRSS Web Interface

Go to https://feeds.fig.systems and log in with your regular credentials.

### Step 2: Navigate to Profile Settings

1. Click your username (top right)
2. Select **"Configuration"** or **"Settings"**
3. Go to the **"Profile"** tab

### Step 3: Generate API Password

1. Scroll down to **"API management"** section
2. Find **"API password"** field
3. Click **"Generate"** or **"Regenerate"** button
4. Copy the generated API password (it will look like a random string)

Example: `hKm9xP3zQwRt2nLv8YbJ`

### Step 4: Use API Password in iOS App

When configuring your iOS RSS app:

**Username:** `eddie` (your FreshRSS username)
**Password:** `[THE GENERATED API PASSWORD]` ← NOT your web password!
**Server URL:** `https://feeds.fig.systems`

### Common iOS RSS Apps Configuration

#### **Reeder**
- Account Type: FreshRSS
- Server: `https://feeds.fig.systems`
- Username: `eddie`
- Password: [API password]

#### **NetNewsWire**
- Account Type: FreshRSS
- URL: `https://feeds.fig.systems`
- Username: `eddie`
- Password: [API password]

#### **Unread**
- Service: FreshRSS (Google Reader-compatible)
- Server: `https://feeds.fig.systems`
- Username: `eddie`
- Password: [API password]

#### **Fiery Feeds**
- Account Type: FreshRSS
- Server URL: `https://feeds.fig.systems`
- Username: `eddie`
- Password: [API password]

## Verify API is Enabled

If the API password doesn't work, verify API is enabled:

1. Log into FreshRSS web interface
2. Go to **Administration** → **Configuration** → **System**
3. Scroll to **"API (mobile access)"**
4. Ensure **"Enable API"** is checked ✓
5. Click **"Submit"** if you made changes

## Troubleshooting

### Error: "Invalid API password"

**Solution:** Regenerate the API password in FreshRSS web interface and try again.

### Error: "Connection failed" or "Cannot connect to server"

**Check:**
1. URL is exactly: `https://feeds.fig.systems` (no trailing slash)
2. Phone has internet connection
3. Try accessing the URL in Safari/Chrome on the same phone
4. Check if Tinyauth SSO is blocking API access

### SSO/Tinyauth Blocking API Access

FreshRSS has `tinyauth` middleware enabled. This might block API requests if they don't have proper authentication headers.

**Check logs:**
```bash
tail -f /home/eduardo_figueroa/homelab/compose/services/FreshRSS/config/log/nginx/access.log
```

Look for your iOS app's requests (they'll have User-Agent like "Reeder" or "NetNewsWire").

**If API is being blocked by SSO:**

Option 1: Create a bypass for API endpoint:
```yaml
# In compose.yaml, change:
traefik.http.routers.freshrss.middlewares: tinyauth

# To bypass API paths:
traefik.http.routers.freshrss.middlewares: freshrss-auth

# Add new middleware in Traefik config or labels:
traefik.http.middlewares.freshrss-auth.chain.middlewares: tinyauth-skip-api, tinyauth
```

Option 2: Temporarily disable SSO to test:
```bash
# Comment out in compose.yaml:
# traefik.http.routers.freshrss.middlewares: tinyauth

docker compose up -d
```

### Error: "SSL/Certificate error"

Your FreshRSS uses Let's Encrypt SSL. If iOS app shows certificate errors:
1. Update iOS to latest version
2. Try toggling "Allow self-signed certificates" OFF (you don't need it)
3. Check the URL doesn't have `http://` (must be `https://`)

## View API Logs

### Check what the iOS app is sending:

```bash
# Watch nginx access log
tail -f /home/eduardo_figueroa/homelab/compose/services/FreshRSS/config/log/nginx/access.log

# Filter for API requests
grep -i "api\|fever\|greader" /home/eduardo_figueroa/homelab/compose/services/FreshRSS/config/log/nginx/access.log | tail -20
```

### Check for authentication errors:

```bash
# PHP errors
tail -f /home/eduardo_figueroa/homelab/compose/services/FreshRSS/config/log/php_errors.log

# Nginx errors
tail -f /home/eduardo_figueroa/homelab/compose/services/FreshRSS/config/log/nginx/error.log
```

### Real-time monitoring:

```bash
# Open 3 terminals and watch:
# Terminal 1:
tail -f /home/eduardo_figueroa/homelab/compose/services/FreshRSS/config/log/nginx/access.log

# Terminal 2:
tail -f /home/eduardo_figueroa/homelab/compose/services/FreshRSS/config/log/nginx/error.log

# Terminal 3:
tail -f /home/eduardo_figueroa/homelab/compose/services/FreshRSS/config/log/php_errors.log

# Now try connecting from iOS app
```

## Quick Test: API is Working

Test the API manually:

```bash
# Replace with your actual API password
API_PASSWORD="your-api-password-here"

# Test authentication
curl -s "https://feeds.fig.systems/api/greader.php/reader/api/0/token" \
  -u "eddie:$API_PASSWORD" | head -20

# Should return a token, not an error
```

If this works, your API is functional and the issue is with how the iOS app is configured.

## Current Status

✅ **Debug logging enabled** - PHP errors will show in logs
✅ **API enabled** - Checked in config.php (line 20)
⚠️ **SSO might block API** - Tinyauth middleware is active

**Next step:** Generate API password and try it in your iOS app!