BookStack MFA Setup

Last Verified: 2026-02-17 | Owner: John

BookStack MFA and API Token Setup

Service: BookStack Knowledge Base URL: http://localhost:6875 or http://192.168.68.61:6875

Overview

This runbook covers:

Setting up Multi-Factor Authentication (MFA) for admin accounts
Creating new API tokens after admin account changes
Security best practices

Prerequisites

BookStack is running and accessible
Admin account: [email protected] (password: BkStk_J0hn_2026!Secure)
Browser access to BookStack web interface

Part 1: Enable MFA (Multi-Factor Authentication)

Open browser and navigate to http://localhost:6875
Click "Sign In"
Enter credentials:
- Email: [email protected]
- Password: BkStk_J0hn_2026!Secure

Step 2: Access Account Settings

Click on your profile icon (top-right corner)
Select "Edit Profile" or "My Account"

Step 3: Enable MFA

Scroll to "Multi-Factor Authentication" section
Click "Setup MFA"
Choose method:
- TOTP (Recommended): Time-based One-Time Password (Google Authenticator, Authy, etc.)
- Backup Codes: Generate backup recovery codes
For TOTP setup:
- Scan QR code with authenticator app
- Enter 6-digit verification code
- Save backup codes in secure location (~/system/config/bookstack-mfa-backup.txt)
Click "Confirm" to enable MFA

Step 4: Test MFA

Log out
Log back in with same credentials
Verify you're prompted for MFA code
Enter code from authenticator app
Successful login confirms MFA is working

Part 2: Create New API Token

The old API token was invalidated when the default [email protected] account was deleted. You need to create a new token for the [email protected] account.

Step 1: Navigate to API Settings

Step 2: Create Token

Click "Create Token"
Enter token details:
- Name: System Integration Token
- Expiry: Never (or set appropriate expiry)
Click "Save"

Step 3: Copy Token Credentials

IMPORTANT: Token secret is only shown once!

You will see:

Token ID: (example: jpipe2-abc123xyz)
Token Secret: (long hexadecimal string)

Copy both values immediately.

Step 4: Update Config File

Update ~/system/config/bookstack.json with new token:

# Edit the config file
nano ~/system/config/bookstack.json

Replace token_id and token_secret with new values:

{
  "url": "http://localhost:6875",
  "external_url": "http://192.168.68.61:6875",
  "token_id": "YOUR_NEW_TOKEN_ID",
  "token_secret": "YOUR_NEW_TOKEN_SECRET",
  "admin_email": "[email protected]",
  "admin_password": "BkStk_J0hn_2026!Secure",
  "alem_email": "[email protected]",
  "alem_password": "V4YawdA13PdsRBIOtFz9"
}

Save the file (Ctrl+O, Enter, Ctrl+X in nano).

Step 5: Test API Token

# Read token from config
TOKEN_ID=$(cat ~/system/config/bookstack.json | grep token_id | cut -d'"' -f4)
TOKEN_SECRET=$(cat ~/system/config/bookstack.json | grep token_secret | cut -d'"' -f4)

# Test API call
curl -s -H "Authorization: Token $TOKEN_ID:$TOKEN_SECRET" http://localhost:6875/api/shelves

Expected: JSON response with list of shelves.

If you see {"error":{"message":"No matching API token was found"...}}, the token is incorrect.

Part 3: Additional Security Measures

Disable Guest Access (Optional)

If you want to require authentication for all access:

Edit docker-compose.yml:

cd ~/system/services/bookstack
nano docker-compose.yml

Change:

- ALLOW_GUEST_ACCESS=true

to:

- ALLOW_GUEST_ACCESS=false

Restart BookStack:
```
docker compose restart bookstack
```

Review User Permissions

Enable Audit Log

Settings → Audit Log
Enable logging of user actions
Review periodically for suspicious activity

Regular Backups

Ensure regular backups are configured:

# Database backup
docker exec bookstack_db mysqldump -u bookstack -p8CdydCxVBD7wBoCVRXZE bookstackapp | gzip > ~/backups/bookstack-$(date +%Y%m%d).sql.gz

# Data backup
cd ~/system/services/bookstack
tar -czf ~/backups/bookstack-data-$(date +%Y%m%d).tar.gz data/

Add to daily cron job or LaunchAgent.

Troubleshooting

MFA Not Working

Solutions:

Check time sync on server and phone (TOTP requires accurate time)
Use backup codes if available

Reset MFA via database (emergency only):

docker exec bookstack_db mysql -u bookstack -p8CdydCxVBD7wBoCVRXZE bookstackapp \
  -e "UPDATE users SET mfa_values = NULL WHERE email = '[email protected]';"

Lost API Token

Problem: Token was not saved and is no longer visible

Solution:

Delete old token in web UI (API Tokens tab)
Create new token (see Part 2)
Update config file

Cannot Access Web UI

Problem: BookStack returns 500 error or won't load