From 289b5f3856c44f930d847dd9ab6a8b3f74c11123 Mon Sep 17 00:00:00 2001
From: Keith Smith <keith@firebugit.com>
Date: Wed, 15 Apr 2026 17:47:49 -0600
Subject: [PATCH] Document self-registration toggle

---
 API.md            | 11 +++++++++--
 README.md         | 22 ++++++++++++++++++----
 stack.env.example |  6 +++++-
 3 files changed, 32 insertions(+), 7 deletions(-)

diff --git a/API.md b/API.md
index 4ea5f82..fba55dd 100644
--- a/API.md
+++ b/API.md
@@ -162,7 +162,12 @@ X-RateLimit-Reset: 1234567890
 
 **POST** `/api/users/register/` (Public)
 
-Creates new user account and sends verification email.
+Creates a new user account and sends a verification email when self-registration is enabled.
+
+**Availability:**
+- Controlled by `ALLOW_SELF_REGISTRATION`
+- Disabled by default
+- Returns `403 Forbidden` when self-registration is off
 
 **Request:**
 ```json
@@ -1056,7 +1061,7 @@ Use `page` query parameter to navigate: `?page=2`
 
 ### Complete Workflow Example
 
-**1. Register:**
+**1. Register:** `ALLOW_SELF_REGISTRATION=True` only
 ```bash
 POST /api/users/register/
 {
@@ -1067,6 +1072,8 @@ POST /api/users/register/
 }
 ```
 
+**If self-registration is disabled:** create the user through Django admin or another internal provisioning flow, then continue with verification/approval as needed.
+
 **2. Verify Email:**
 ```bash
 POST /api/users/verify-email/
diff --git a/README.md b/README.md
index 36679d8..b334d56 100644
--- a/README.md
+++ b/README.md
@@ -25,8 +25,8 @@ A powerful Django-based task management system with time tracking, tag organizat
 
 ### User Management
 - **Multi-user Support**: Full authentication and user management
-- **Email Verification**: Secure email verification for new user registrations
-- **Admin Approval**: Optional admin approval workflow for new users
+- **Email Verification**: Secure email verification for admin-created or self-registered accounts
+- **Admin Approval**: Optional approval workflow for new users
 - **User Profiles**: Customizable profiles with timezone and notification preferences
 - **Password Management**: Secure password change functionality
 
@@ -119,6 +119,15 @@ Set via environment variable:
 export DJANGO_SETTINGS_MODULE=config.settings.development
 ```
 
+### Registration Control
+
+Self-registration is controlled with `ALLOW_SELF_REGISTRATION`.
+
+- `ALLOW_SELF_REGISTRATION=False` disables public signup and requires an administrator to create accounts
+- `ALLOW_SELF_REGISTRATION=True` enables the `/register/` page and `/api/users/register/` endpoint
+
+If the variable is omitted, self-registration is disabled by default.
+
 ### Database Configuration
 
 The application supports multiple database backends. Choose the one that fits your needs.
@@ -955,11 +964,15 @@ sudo ufw status
 # Log in to the web interface at https://tasks.firebugit.com/admin
 # Use the superuser credentials created in Step 3
 
-# When new users register:
+# If ALLOW_SELF_REGISTRATION=True and new users register:
 # 1. They receive verification email
 # 2. After clicking verification link, you receive admin notification
 # 3. Go to Admin > Users > select user(s) > Actions > "Approve selected users"
 # 4. User receives approval email and can now log in
+#
+# If ALLOW_SELF_REGISTRATION=False:
+# 1. Create users through Django admin or management commands
+# 2. Mark them verified/approved as needed for your onboarding flow
 ```
 
 ### Production Checklist
@@ -994,7 +1007,8 @@ Complete this checklist before going live:
 - [ ] Run `python manage.py migrate` to apply all migrations
 - [ ] Run `python manage.py collectstatic` for static files
 - [ ] Create superuser account for admin access
-- [ ] Test user registration and email verification flow
+- [ ] Confirm `ALLOW_SELF_REGISTRATION` is set correctly for production
+- [ ] Test account onboarding flow (admin-created users or public registration)
 - [ ] Test admin approval workflow
 - [ ] Configure `SITE_DOMAIN` to your production domain
 - [ ] Set appropriate `EMAIL_VERIFICATION_TOKEN_EXPIRY_HOURS`
diff --git a/stack.env.example b/stack.env.example
index 3e9c8f3..2a5b89a 100644
--- a/stack.env.example
+++ b/stack.env.example
@@ -30,6 +30,10 @@ CSRF_TRUSTED_ORIGINS=https://yourdomain.com
 # Domain used in email links
 SITE_DOMAIN=yourdomain.com
 
+# Public self-registration toggle
+# Set to False to require admin-created accounts
+ALLOW_SELF_REGISTRATION=False
+
 # ===================================================================
 # Database Configuration (PostgreSQL)
 # ===================================================================
@@ -47,7 +51,7 @@ REDIS_URL=redis://redis:6379/0
 # ===================================================================
 # Email Configuration
 # ===================================================================
-# Required for user registration (email verification) and notifications
+# Required for email verification, approval emails, and notifications
 
 EMAIL_BACKEND=django.core.mail.backends.smtp.EmailBackend