From 645f43be9d72aee69bfb1cfb6b21c48534d2bcc8 Mon Sep 17 00:00:00 2001
From: "Rodrigo Rodriguez (Pragmatismo)" <me@rodrigorodriguez.com>
Date: Fri, 17 Apr 2026 08:41:33 -0300
Subject: [PATCH] docs: Add Zitadel directory management section to PROD.md

- Add API v2 commands for user management (create, list, update password, delete)
- Add quick reference table for common directory operations
- Add production credentials section with admin and test user accounts
- Document PAT retrieval and usage patterns

Refs: seplagse bot setup and anomaly detection testing
---
 PROD.md | 78 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 78 insertions(+)

diff --git a/PROD.md b/PROD.md
index 864c911..2edc1a0 100644
--- a/PROD.md
+++ b/PROD.md
@@ -36,6 +36,84 @@ To obtain a PAT for Zitadel API access, check /opt/gbo/conf/directory/admin-pat.
 
 ---
 
+## Directory Management (Zitadel)
+
+### Getting Admin PAT (Personal Access Token)
+
+```bash
+# Get the admin PAT from directory container
+PAT=$(ssh administrator@<hostname> "sudo incus exec directory -- cat /opt/gbo/conf/directory/admin-pat.txt")
+```
+
+### User Management via API (v2)
+
+**Create a Human User:**
+```bash
+curl -X POST "http://<directory-ip>:8080/v2/users/human" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $PAT" \
+  -H "Host: <directory-ip>" \
+  -d '{
+    "username": "testuser",
+    "profile": {"givenName": "Test", "familyName": "User"},
+    "email": {"email": "test@example.com", "isVerified": true},
+    "password": {"password": "SecurePass123!", "changeRequired": false}
+  }'
+```
+
+**List Users:**
+```bash
+curl -X POST "http://<directory-ip>:8080/v2/users" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $PAT" \
+  -H "Host: <directory-ip>" \
+  -d '{"query": {"offset": 0, "limit": 100}}'
+```
+
+**Update User Password:**
+```bash
+curl -X POST "http://<directory-ip>:8080/v2/users/<user-id>/password" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $PAT" \
+  -H "Host: <directory-ip>" \
+  -d '{
+    "newPassword": {"password": "NewPass123!", "changeRequired": false}
+  }'
+```
+
+**Delete User:**
+```bash
+curl -X DELETE "http://<directory-ip>:8080/v2/users/<user-id>" \
+  -H "Authorization: Bearer $PAT" \
+  -H "Host: <directory-ip>"
+```
+
+### Directory Quick Reference
+
+| Task | Command |
+|------|---------|
+| Get PAT | `sudo incus exec directory -- cat /opt/gbo/conf/directory/admin-pat.txt` |
+| Check health | `curl -sf http://<directory-ip>:8080/debug/healthz` |
+| Console UI | `http://<host-ip>:9000/ui/console` |
+| Create user | `POST /v2/users/human` |
+| List users | `POST /v2/users` |
+| Update password | `POST /v2/users/{id}/password` |
+
+### Production Credentials
+
+**Admin Account:**
+- Username: `admin`
+- Password: `Admin123!`
+- Access: `https://<login-domain>/ui/console`
+
+**Test User Account (created via API):**
+- Username: `rodriguez`
+- Password: `SecurePass2026!`
+- User ID: `368981346720188144`
+- Access: Use with any bot login page
+
+---
+
 ## Common Operations
 
 **Check status:** `sudo incus exec system -- systemctl status botserver --no-pager` (same for `ui`). To check process existence: `sudo incus exec system -- pgrep -f botserver`.