Docs: document the Bearer API (endpoints, scopes) in README + admin page

- README: Bearer API table (list/read/comment/status), scope explanation,
  and the new endpoints in the API Endpoints table.
- /admin/api-keys API Usage section: scopes note + copy-paste cURL examples
  for create, list/triage, read-one, comment, and close (uses APP_DOMAIN).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

README.md

@@ -94,11 +94,22 @@ The following features are intentionally **not planned** for this system:
 - **Required Fields**: Mark fields as required for validation
 
 ### API Key Management
-- **Admin UI**: Generate and manage API keys at `/admin/api-keys`
+- **Admin UI**: Generate and manage API keys at `/admin/api-keys` (paginated)
 - **Bearer Token Auth**: Use API keys with `Authorization: Bearer YOUR_KEY` header
+- **Key Scopes**: `read` (GET only) or `read_write` (create/comment/close). A `read` key cannot mutate anything, including creating tickets. Existing keys default to `read_write`.
 - **Expiration**: Optional expiration dates for keys
 - **Revocation**: Revoke compromised keys instantly
 
+### Bearer API (automation / triage)
+All Bearer-authenticated, rate-limited, and (like `create_ticket_api.php`) exempt from Authelia at the reverse proxy — the API key is the only credential. Comments/closes made via the API are attributed to the **key's name** (linked to the key's owner).
+
+| Endpoint | Method | Scope | Purpose |
+|----------|--------|-------|---------|
+| `/create_ticket_api.php` | POST | read_write | Create a ticket (hwmonDaemon, external tools) |
+| `/api/tickets_api.php` | GET | read | List/triage the queue (`?status=`, `?priority=`, `?host=` [title match], `?page=`, `?limit=`) **or** read one (`?ticket_id=NNN`) with its comments |
+| `/api/ticket_comment_api.php` | POST | read_write | Add a comment: `{ticket_id, comment_text, markdown_enabled?}` |
+| `/api/ticket_status_api.php` | POST | read_write | Change/close status (workflow-validated): `{ticket_id, status, comment?}` — `comment` is required for transitions that require one (e.g. → Closed); it is posted as the close reason in the same call |
+
 ### User Management & Authentication
 - **SSO Integration**: Authelia authentication with LLDAP backend
 - **Role-Based Access**: Admin and standard user roles
@@ -250,6 +261,9 @@ Content-Type: application/json
 | Endpoint | Method | Description |
 |----------|--------|-------------|
 | `/create_ticket_api.php` | POST | Create ticket via API key (hwmonDaemon, external tools) |
+| `/api/tickets_api.php` | GET | Bearer: list/triage queue or read one ticket + comments |
+| `/api/ticket_comment_api.php` | POST | Bearer: add a comment (read_write scope) |
+| `/api/ticket_status_api.php` | POST | Bearer: change/close status, workflow-validated (read_write scope) |
 | `/api/update_ticket.php` | POST | Update ticket with workflow validation |
 | `/api/assign_ticket.php` | POST | Assign ticket to user |
 | `/api/add_comment.php` | POST | Add comment to ticket |

views/admin/ApiKeysView.php

@@ -169,17 +169,56 @@ include __DIR__ . '/../../views/layout_header.php';
       </div>
       <pre><code>Authorization: Bearer YOUR_API_KEY</code></pre>
     </div>
-    <p class="lt-text-xs lt-text-muted" style="margin-top:0.5rem">
+    <?php $apiBase = 'https://' . htmlspecialchars($GLOBALS['config']['APP_DOMAIN'] ?? 'your-instance', ENT_QUOTES); ?>
-      Example — create a ticket via cURL:<br>
+    <p class="lt-text-sm lt-text-muted" style="margin-top:0.75rem">
+      <strong>Scopes:</strong> a <code>read</code> key may only use the <code>GET</code> endpoints;
+      a <code>read_write</code> key may also create tickets, post comments, and change status.
+      All endpoints are Bearer-authenticated and rate-limited. Comments and status changes made via
+      the API are attributed to the key's name.
     </p>
+
+    <p class="lt-text-xs lt-text-muted" style="margin-top:0.75rem"><strong>Create a ticket</strong> (read_write):</p>
     <div class="lt-code-block">
       <div class="lt-code-header"><span class="lt-code-lang">CURL</span></div>
-      <pre><code>curl -X POST https://your-instance/create_ticket_api.php \
+      <pre><code>curl -X POST <?= $apiBase ?>/create_ticket_api.php \
   -H "Authorization: Bearer YOUR_API_KEY" \
   -H "Content-Type: application/json" \
   -d '{"title":"My ticket","category":"General","type":"Issue","priority":3}'</code></pre>
     </div>
-    <p class="lt-text-xs lt-text-muted" style="margin-top:0.5rem">API keys provide programmatic access to create and manage tickets. Keep keys secure and rotate them regularly.</p>
+
+    <p class="lt-text-xs lt-text-muted" style="margin-top:0.75rem"><strong>List / triage the queue</strong> (read). Filters: <code>status</code>, <code>priority</code> (1-5), <code>host</code> (title match), <code>page</code>, <code>limit</code>:</p>
+    <div class="lt-code-block">
+      <div class="lt-code-header"><span class="lt-code-lang">CURL</span></div>
+      <pre><code>curl "<?= $apiBase ?>/api/tickets_api.php?status=Open&priority=2&limit=25" \
+  -H "Authorization: Bearer YOUR_API_KEY"</code></pre>
+    </div>
+
+    <p class="lt-text-xs lt-text-muted" style="margin-top:0.75rem"><strong>Read one ticket + its comments</strong> (read):</p>
+    <div class="lt-code-block">
+      <div class="lt-code-header"><span class="lt-code-lang">CURL</span></div>
+      <pre><code>curl "<?= $apiBase ?>/api/tickets_api.php?ticket_id=123456789" \
+  -H "Authorization: Bearer YOUR_API_KEY"</code></pre>
+    </div>
+
+    <p class="lt-text-xs lt-text-muted" style="margin-top:0.75rem"><strong>Post a comment</strong> (read_write). <code>markdown_enabled</code> is optional:</p>
+    <div class="lt-code-block">
+      <div class="lt-code-header"><span class="lt-code-lang">CURL</span></div>
+      <pre><code>curl -X POST <?= $apiBase ?>/api/ticket_comment_api.php \
+  -H "Authorization: Bearer YOUR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"ticket_id":"123456789","comment_text":"Investigating.","markdown_enabled":true}'</code></pre>
+    </div>
+
+    <p class="lt-text-xs lt-text-muted" style="margin-top:0.75rem"><strong>Change / close status</strong> (read_write, workflow-validated). <code>comment</code> is required for transitions that require one (e.g. closing) and is posted as the reason:</p>
+    <div class="lt-code-block">
+      <div class="lt-code-header"><span class="lt-code-lang">CURL</span></div>
+      <pre><code>curl -X POST <?= $apiBase ?>/api/ticket_status_api.php \
+  -H "Authorization: Bearer YOUR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"ticket_id":"123456789","status":"Closed","comment":"Resolved: disk replaced."}'</code></pre>
+    </div>
+
+    <p class="lt-text-xs lt-text-muted" style="margin-top:0.75rem">Keep keys secure and rotate them regularly. Scope automation keys to <code>read</code> unless they need to write.</p>
   </div>
 </div>