API Endpoints & Integration

Relevant source files

The following files were used as context for generating this wiki page:

• scripts/api.php
• api-examples/authenticate.php
• api-examples/AGENT_NOTES.md
• scripts/scripts.php
• README.md
• wiki/Home.md
• scripts/verify_api_coverage.php

The IT Management system provides a comprehensive set of internal and integration-ready API endpoints designed to handle multi-tenant data operations. These endpoints primarily support AJAX interactions for the web interface and bulk data synchronization through JSON-based import mechanisms.

The API architecture is built on a session-based authentication model with mandatory CSRF protection. It avoids third-party dependencies, relying on native PHP mysqli for database interactions and structured JSON for data exchange. Sources: README.md, scripts/api.php:123-130

Authentication & Security Model

Authentication for API access mirrors the web application's security posture. It requires a valid PHP session cookie (PHPSESSID) and a CSRF token. The system enforces multi-tenancy at the session level; the company_id is derived server-side from the authenticated session and should not be included in API payloads to prevent tenant-crossing. Sources: scripts/api.php:143-155, api-examples/AGENT_NOTES.md:7-9

Authentication Flow

The following diagram illustrates the process of acquiring a session and token for subsequent API calls.

The system uses session-based auth rather than JWT. Sources: scripts/api.php:125, api-examples/authenticate.php

Endpoint Categories

1. Module Import APIs

Most standard CRUD modules expose a JSON import endpoint at their respective index.php file. These endpoints are utilized by the js/table-tools.js utility to process Excel/CSV data. Sources: scripts/api.php:177-183, scripts/verify_api_coverage.php:12-14

Module	Path	Method	Purpose
Departments	modules/departments/index.php	POST	Bulk import via import_excel_rows
Equipment	modules/equipment/index.php	POST	Multi-row equipment import
Employees	modules/employees/index.php	POST	Directory import with lookup resolution
Tickets	modules/tickets/index.php	POST	Bulk ticket creation

2. IDF & Infrastructure APIs

Specialized endpoints under modules/idfs/api/ handle the complex synchronization required for rack management and port connectivity. Sources: scripts/api.php:164-173

These endpoints are POST-only and require JSON payloads. Sources: scripts/api.php:165, scripts/api.php:111-112

3. Utility & System Endpoints

System-wide utilities provide metadata, search capabilities, and administrative functions. Sources: scripts/api.php:97-120

• Port Management: includes/get_ports.php and includes/update_port.php handle switch port metadata and auto-sync with idf_ports.
• Database Schema: scripts/DBdesign.php?format=json provides the ER diagram data in JSON format.
• File Management: modules/explorer/api.php handles file actions including create, rename, delete, and move.
• Organization: modules/org_chart/index.php processes hierarchy updates via drag-and-drop actions.

Data Exchange Format

Data is exchanged using JSON. A typical successful response includes an ok boolean and the number of affected rows. Sources: scripts/api.php:189-195

Sample Import Payload

{
    "csrf_token": "a1b2c3d4...",
    "import_excel_rows": [
        ["Name", "Active"],
        ["IT Department", "1"],
        ["Human Resources", "1"]
    ]
}

Sources: scripts/api.php:189-195

Error Handling & Validation

The API uses standard HTTP status codes to communicate result states.

Status	Message	Context
400	Invalid CSRF token	Missing or mismatched token.
401	Unauthorized	Session expired or invalid.
403	Access Denied	Permission or tenant scope violation.
405	Method not allowed	Incorrect HTTP verb (e.g., GET on POST endpoint).
500	DB error	Internal SQL or schema constraint failure.

Sources: scripts/api.php:218-227

Integration Guidelines

1. Session Capture: External tools must capture the PHPSESSID cookie from the login response. Sources: api-examples/AGENT_NOTES.md:15-17
2. CSRF Extraction: The CSRF token must be extracted from the HTML content of an authenticated page (e.g., dashboard) or passed in headers. Sources: scripts/api.php:124-126
3. Tenant Safety: Never attempt to pass company_id in the payload; the server automatically restricts operations to the company associated with the active session. Sources: scripts/api.php:127-130
4. CLI Interaction: Utility scripts for maintenance and testing (e.g., scripts/run_tests.php) must define ITM_CLI_SCRIPT to bypass standard session redirects. Sources: scripts/scripts.php:2, scripts/AGENT_NOTES.md:11-13

The API system is integral to the project's "zero-dependency" philosophy, providing a robust but lightweight interface for both the internal UI and external automation. Sources: README.md, wiki/Home.md