Admin Guide — API Keys & Classified Business Onboarding

Staff Admin
1

API Keys & Classified Business Onboarding

API Keys

FAOL uses Discourse API keys for automation and admin tools. Never share API keys in posts or public channels.

Where API Keys Are Used

Tool Key Type Where Stored Purpose
apply_theme.py Global system key .env on workstation Apply theme CSS/JS to Discourse
onboard_shop.py Global system key tools/onboard-shop/.env Create classified shop listings
Games Admin (admin.html) User session (CSRF) Browser cookie Read/write game data topics
Leaderboard (leaderboard.js) User session (CSRF) Browser cookie Post scores

Creating a New API Key

  1. Go to Admin → API (/admin/api/keys)
  2. Click New API Key
  3. Settings:
    • Description: What it’s for (e.g., “FAOL deploy tools”)
    • User Level: All Users
    • Scope: Global (Read, Write)
  4. Click Save
  5. Copy the key immediately — it’s only shown once
  6. Update the relevant .env file with the new key

Rotating Keys

If a key is compromised:

  1. Go to Admin → API
  2. Find the old key → Revoke
  3. Create a new key (steps above)
  4. Update all .env files that reference the old key
  5. Test: curl -s -H 'Api-Key: NEW_KEY' -H 'Api-Username: system' https://www.flyanglersonline.com/site.json | head -1

Current Keys

Description Created Notes
FAOL deploy tools Apr 2026 Used by apply_theme.py and onboard_shop.py

Key values are stored in .env files on the workstation — never committed to git.

Classified Business Onboarding (Fly Shops)

This is for the Classifieds > Fly Shops directory — not advertising. When a fly shop responds to our outreach and wants a free classified listing, an admin onboards them using a Python script.

Prerequisites

  • SSH access to the workstation
  • Python 3 with requests and python-dotenv
  • The tools/onboard-shop/ directory with a configured .env

Setup (one-time)

cd tools/onboard-shop
cp .env.example .env
# Edit .env with:
#   DISCOURSE_URL=https://www.flyanglersonline.com
#   DISCOURSE_API_KEY=<your key from Admin → API>
#   DISCOURSE_API_USERNAME=system

To get the API key: Admin → API → find the “FAOL deploy tools” key, or create a new one.

Onboarding a Shop

Interactive mode:

cd tools/onboard-shop
python onboard_shop.py

You’ll be prompted for:

  • Shop name
  • Email address
  • Location (City, ST)
  • Website URL
  • Description (optional — they can edit later)

Non-interactive mode:

python onboard_shop.py --name "Trout Creek Flies" \\
  --email "info@troutcreekflies.com" \\
  --location "Dutch John, UT" \\
  --website "https://troutcreekflies.com" \\
  --description "" -y

What the Script Does

  1. Checks for duplicates — warns if email or shop name already exists
  2. Creates a Discourse account — generates username from shop name, random password
  3. Adds to verified_business group — gives them edit rights on their listing
  4. Creates classified listing in Fly Shops (category 24) — authored as the business user
  5. Sends welcome message — PM with instructions on editing their listing

What the Shop Gets

  • One classified listing in the Fly Shops directory that they can edit
  • Members can reply with testimonials
  • They cannot create additional topics (staff-only create)
  • Their password is shown in the script output — share it securely

Category Permissions (Fly Shops, cat 24)

Who Can Do
Staff Create + Reply
Everyone (logged in) Reply only
Anonymous Read only
Business owner Edit their own classified listing

Email Template

The outreach email template is at marketing/email_template.md in the workspace. When a shop replies, run the onboard script.