From 6558a4043565cf1ccbfb6f69863719f2d3fb39d2 Mon Sep 17 00:00:00 2001
From: root <root@dev.lohmar.co.uk>
Date: Wed, 24 Jun 2026 19:17:39 +0000
Subject: [PATCH] Add POSTMAN_GUIDE.md with setup, endpoints, and
 troubleshooting

---
 POSTMAN_GUIDE.md | 168 +++++++++++++++++++++++++++++++++++++++++++++++
 README.md        |   3 +
 2 files changed, 171 insertions(+)
 create mode 100644 POSTMAN_GUIDE.md

diff --git a/POSTMAN_GUIDE.md b/POSTMAN_GUIDE.md
new file mode 100644
index 0000000..9947982
--- /dev/null
+++ b/POSTMAN_GUIDE.md
@@ -0,0 +1,168 @@
+# Authelia API - Postman Collection
+
+This directory contains Postman files for testing and interacting with the Authelia API.
+
+## Files
+
+- `authelia-api.postman_collection.json` - Main Postman collection with all API endpoints
+- `authelia-api.postman_environment.json` - Environment variables for easy configuration
+- `src/test_bulk.json` - Example request body for bulk user creation
+
+## Setup Instructions
+
+### 1. Import into Postman
+
+1. Open Postman
+2. Click **Import** button
+3. Select both the collection and environment files
+4. Click **Import**
+
+### 2. Configure Environment
+
+1. In Postman, select the **"Authelia API"** environment from the environment dropdown (top-right)
+2. Click the eye icon next to the environment name
+3. Set the following variables:
+
+| Variable | Value | Description |
+|----------|-------|-------------|
+| `base_url` | `http://127.0.0.1:8080` | API base URL (default) |
+| `bearer_token` | Your session.secret | **Required** - Get from Authelia config |
+
+### 3. Get Your Bearer Token
+
+The initial bearer token is your Authelia `session.secret`:
+
+```bash
+# Extract from Authelia configuration
+grep -A2 "session:" /opt/authelia/configuration.yml | grep "secret:" | awk '{print $2}'
+```
+
+Example token: `5DdUKe12k6niaaekpTeB0H35A48xmTWBWJcI3AOoqPA=`
+
+**Security Note:** This token provides full API access. Keep it secure!
+
+## API Endpoints
+
+### Health Check
+- **GET** `/api/health`
+- No authentication required
+- Returns API status and version
+
+### Bulk Create Users
+- **POST** `/api/users/bulk`
+- Requires Bearer token
+- Creates multiple users with auto-generated passwords
+- Example request body in `src/test_bulk.json`
+
+### List Users
+- **GET** `/api/users`
+- Requires Bearer token
+- Lists all users in the system
+
+### Delete User
+- **DELETE** `/api/users/{username}`
+- Requires Bearer token
+- Deletes a user by username
+
+## Testing Workflow
+
+1. **Health Check**: Verify API is running
+2. **Bulk Create**: Add test users (see example below)
+3. **List Users**: Confirm users were created
+4. **Delete User**: Clean up test users
+
+### Example: Create Test Users
+
+Use the pre-configured request in the collection, or modify the body:
+
+```json
+{
+  "users": [
+    {
+      "username": "test.user1",
+      "display_name": "Test User One",
+      "email": "test1@example.com",
+      "groups": ["users", "developers"]
+    },
+    {
+      "username": "test.user2",
+      "display_name": "Test User Two",
+      "email": "test2@example.com",
+      "groups": ["users"]
+    }
+  ]
+}
+```
+
+## Response Examples
+
+### Health Check
+```json
+{
+  "status": "ok",
+  "version": "dev",
+  "time": "2026-04-02T00:00:00Z"
+}
+```
+
+### Bulk Create Success
+```json
+{
+  "success": true,
+  "created": 2,
+  "users": [
+    {
+      "username": "john.doe",
+      "display_name": "John Doe",
+      "email": "john.doe@example.com",
+      "placeholder_password": "aB3$fG7!kL9*mN2@pQ",
+      "status": "created"
+    }
+  ]
+}
+```
+
+### List Users
+```json
+[
+  {
+    "username": "john.doe",
+    "display_name": "John Doe",
+    "email": "john.doe@example.com",
+    "groups": ["users", "admins"],
+    "disabled": false,
+    "created_at": "2026-04-02 00:00:00",
+    "updated_at": "2026-04-02 00:00:00"
+  }
+]
+```
+
+## Troubleshooting
+
+### 401 Unauthorized
+- Check that `bearer_token` is set in environment
+- Verify token matches Authelia `session.secret`
+- Ensure `Authorization` header is present
+
+### Connection Refused
+- Verify Authelia API is running: `systemctl status authelia-api`
+- Check API port: Default is `127.0.0.1:8080`
+- Ensure firewall allows local connections
+
+### 400 Bad Request
+- Validate JSON request body format
+- Check required fields: `username`, `display_name`, `email`
+- Ensure email contains '@' symbol
+
+## Next Steps
+
+1. Test API with actual user data
+2. Configure SMTP for email onboarding (if needed)
+3. Set up monitoring/alerting for API health
+4. Consider rotating bearer tokens for production
+
+## Related Resources
+
+- [Authelia API Source Code](../src/)
+- [Installation Guide](README.md)
+- [Authelia Documentation](https://www.authelia.com/)
diff --git a/README.md b/README.md
index ca3ca91..d7d90bd 100644
--- a/README.md
+++ b/README.md
@@ -91,6 +91,9 @@ Postman collection and environment files are provided for API testing:
 
 - `authelia-api.postman_collection.json` - Complete API collection with all endpoints
 - `authelia-api.postman_environment.json` - Environment variables (base URL, token)
+- `POSTMAN_GUIDE.md` - Setup and usage guide
+
+See [POSTMAN_GUIDE.md](POSTMAN_GUIDE.md) for detailed setup and usage instructions.
 
 ## Files in This Repository