Bookhoard/bookhoard
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 12 Wiki Activity

docs: update Kobo setup to use API key authentication

Browse Source 
- Replace username/password authentication with API key in sync URL
- Update configuration examples to show API key in URL path
- Add instructions for copying API key from Device Management
- Update OPDS catalog URL to include token parameter
- Fix troubleshooting section for API key authentication
- Document where to find API key and sync URL in UI
- Update SSL/TLS examples with API key approach
This commit is contained in:
john-okeefe
2026-02-12 10:52:43 -05:00
parent b1345e1ad7
commit e359fe73cb
1 changed files with 37 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/user/devices/kobo-setup.md
+37 -18
View File
@@ -99,6 +99,8 @@ Your device is now registered and ready for configuration!
### Step 3: Add Bookhoard Sync Configuration
After device registration is complete, you'll receive an API key and sync URL from Bookhoard.
Add the following section to the end of your `Kobo eReader.conf` file:
```ini
@@ -107,16 +109,30 @@ Add the following section to the end of your `Kobo eReader.conf` file:
KoboStoreSyncDisabled=true
[Sync]
# Bookhoard Sync Configuration
ServerURL=http://YOUR_COMPUTER_IP:8765/api/sync/kobo
# Bookhoard Sync Configuration (from Device Management page)
ServerURL=http://YOUR_COMPUTER_IP:8765/api/sync/kobo/YOUR_API_KEY
AutoSyncEnabled=true
SyncFrequency=5
# Authentication
Username=YOUR_BOOKHOARD_USERNAME
Password=YOUR_BOOKHOARD_PASSWORD
```
**Where to find these values**:
- `YOUR_COMPUTER_IP`: Your Bookhoard server's IP address (e.g., 192.168.1.100)
- `YOUR_API_KEY`: Copy from Bookhoard Device Management → Your Kobo Device → "Copy Sync URL"
**Example configuration**:
```ini
[Sync]
ServerURL=http://192.168.1.100:8765/api/sync/kobo/dev_abc123def456
AutoSyncEnabled=true
SyncFrequency=5
```
**Important Notes**:
- The API key is generated during device registration
- You can regenerate the API key anytime from Device Management if needed
- Keep your API key confidential like a password
- Bookhoard uses revocable API keys for security (not username/password)
**Replace the following with your actual values**:
- `YOUR_COMPUTER_IP`: Your computer's local IP address (e.g., 192.168.1.100)
- `YOUR_BOOKHOARD_USERNAME`: Your Bookhoard email or username
@@ -204,15 +220,16 @@ OPDS (Open Publication Distribution System) allows your Kobo to **wirelessly dow
[FeatureSettings]
# Enable OPDS catalog
OPDSCatalogEnabled=true
OPDSCatalogURL=http://YOUR_COMPUTER_IP:8765/opds/devices/YOUR_DEVICE_ID/catalog
OPDSCatalogURL=http://YOUR_COMPUTER_IP:8765/opds/devices/YOUR_DEVICE_ID/catalog?token=YOUR_API_KEY
# Example:
# OPDSCatalogURL=http://192.168.1.100:8765/opds/devices/kobo-clara-123/catalog
# OPDSCatalogURL=http://192.168.1.100:8765/opds/devices/kobo-clara-123/catalog?token=dev_abc123def456
```
4. Replace:
- `YOUR_COMPUTER_IP`: Your Bookhoard server IP
- `YOUR_DEVICE_ID`: Your Kobo's device ID from Bookhoard Device Management
- `YOUR_API_KEY`: Your Kobo device's API key (same as in sync URL)
5. Save the file and safely eject your Kobo
@@ -424,9 +441,11 @@ If you have SSL/TLS configured on Bookhoard:
```ini
[Sync]
ServerURL=https://bookhoard.yourdomain.com/api/sync/kobo
ServerURL=https://bookhoard.yourdomain.com/api/sync/kobo/YOUR_API_KEY
```
Replace `YOUR_API_KEY` with your device's API key from Bookhoard Device Management.
Kobo will automatically trust the certificate if properly configured.
## Troubleshooting
@@ -455,14 +474,14 @@ Kobo will automatically trust the certificate if properly configured.
### Authentication Failed
**Problem**: "Authentication failed" or "Invalid credentials"
**Problem**: "Authentication failed" or "Invalid API key"
**Solutions**:
1. Verify username and password in config file
2. Check your account is active and not locked
3. Try logging in to Bookhoard web interface
4. Ensure password doesn't contain special characters that need escaping
5. Reset password if needed
1. Verify the API key in your sync URL matches the one in Bookhoard Device Management
2. Check that device is approved in Bookhoard (not pending)
3. Try regenerating the API key from Device Management page
4. Ensure the sync URL is complete (includes the API key)
5. Copy the sync URL directly from Device Management → "Copy Sync URL" button
### Configuration File Not Saving
@@ -532,10 +551,10 @@ For access outside your home network:
1. Set up port forwarding on your router (port 8765)
2. Configure SSL/TLS on Bookhoard
3. Use a dynamic DNS service for constant hostname
4. Update Kobo config with public URL:
4. Update Kobo config with public URL including API key:
```ini
[Sync]
ServerURL=https://yourdomain.com/api/sync/kobo
ServerURL=https://yourdomain.com/api/sync/kobo/YOUR_API_KEY
```
## Performance Optimization