From d81fdf4104767f09174fd8d7e391e6730db69ae3 Mon Sep 17 00:00:00 2001 From: Jared Vititoe Date: Wed, 15 Jul 2026 19:16:42 -0400 Subject: [PATCH] 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 --- README.md | 16 ++++++++++++- views/admin/ApiKeysView.php | 47 +++++++++++++++++++++++++++++++++---- 2 files changed, 58 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index b322062..3f0ce79 100644 --- a/README.md +++ b/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 | diff --git a/views/admin/ApiKeysView.php b/views/admin/ApiKeysView.php index 08d194d..24b8e6e 100644 --- a/views/admin/ApiKeysView.php +++ b/views/admin/ApiKeysView.php @@ -169,17 +169,56 @@ include __DIR__ . '/../../views/layout_header.php'; 
Authorization: Bearer YOUR_API_KEY
-

- Example — create a ticket via cURL:
+ +

+ Scopes: a read key may only use the GET endpoints; + a read_write 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.

+ +

Create a ticket (read_write):

CURL
- 
curl -X POST https://your-instance/create_ticket_api.php \
+      
curl -X POST /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}'
-

API keys provide programmatic access to create and manage tickets. Keep keys secure and rotate them regularly.

+ +

List / triage the queue (read). Filters: status, priority (1-5), host (title match), page, limit:

+
+
CURL
+ 
curl "/api/tickets_api.php?status=Open&priority=2&limit=25" \
+  -H "Authorization: Bearer YOUR_API_KEY"
+
+ +

Read one ticket + its comments (read):

+
+
CURL
+ 
curl "/api/tickets_api.php?ticket_id=123456789" \
+  -H "Authorization: Bearer YOUR_API_KEY"
+
+ +

Post a comment (read_write). markdown_enabled is optional:

+
+
CURL
+ 
curl -X POST /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}'
+
+ +

Change / close status (read_write, workflow-validated). comment is required for transitions that require one (e.g. closing) and is posted as the reason:

+
+
CURL
+ 
curl -X POST /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."}'
+
+ +

Keep keys secure and rotate them regularly. Scope automation keys to read unless they need to write.