Differences

This shows you the differences between two versions of the page.

--- api [2023/09/14 20:15] – created johnny
+++ api [2025/06/09 15:26] (current) – added "API Reference Guide" dalton
@@ Line 2: / Line 2: @@
-Use ITFlow's API to work with ITFlow in scripts and (eventually) third-party apps.
+Use ITFlow's API to work with ITFlow in scripts third-party applications.
-The current version of the ITFlow API is v1. It can be accessed at **/api/v1/{module}/{function}.php**
+The current version of the ITFlow API is v1. It can be accessed at **itflow.example.com/api/v1/{module}/{function}.php**
+===== Generating an API Key =====
+  - Login and navigate to the **Admin Settings** page
+  - Select **API Keys**
+  - Select **Create** to open the New Key modal
+  - On Details tab, input the key name and expiration date. Select whether the key will allow access to all clients or a specific client
+  - On Keys tab, note down the API key and credential password and select the checkbox to confirm you've made a copy of the keys. You will not see these admin in the admin interface.
+  - Select Create to add the key into the database
 ===== Modules with API support at present =====
@@ Line 10: / Line 19: @@
   * assets
   * certificates
+  * clients
   * contacts
+  * credentials (logins)
   * domains
   * networks
@@ Line 20: / Line 31: @@
   * read
-  * create (partial)
+  * create //(partial)//
-  * update (partial)
+  * update //(partial)//
+  * delete //(partial)//
-===== Generating an API Key =====
-  - Navigate to the Admin panel
-  - Click on API
-  - Click on New Key to generate a new key
+  * //We may also add archive//
 ===== Request Methods =====
@@ Line 45: / Line 53: @@
 ==== Notes ====
-  * For read requests, 50 records are shown by default. This can be adjusted by supplying the limit and offset parameters.
+  * For read requests, 50 records are shown by default. This can be adjusted by supplying the ''limit'' and ''offset'' parameters.
-  * For POST requests, the client_id parameter is always required if the API key used has scope/access to all clients
+  * For POST requests, the ''client_id'' parameter is always required if the API key used has scope/access to all clients
+  * Be sure to check your Apache/PHP error logs if you're running into issues
 ==== API Docs/Examples ====
-Documentation / an example of how to use a module API endpoint is shown on that module's doc page. Additional examples are available here.
+Documentation / an example of how to use a module API endpoint is shown on that module's doc page. Additional examples are available [[https://github.com/itflow-org/itflow-api-powershell|here]].
+----
+====== API Reference Guide ======
+**Current API v1 Endpoints, Authentication, Examples, and Integration Guide**
+===== Quick Start Guide =====
+==== Your First API Call in 5 Minutes ====
+  - **Generate API Key**
+    - Login to ITFlow as admin
+    - Navigate to **Admin > API**
+    - Click **New Key**
+    - Choose scope: **All Clients** (for testing) or **Specific Client**
+    - Copy the generated key
+  - **Test Connection**
+<code bash>
+curl "https://itflow.yourdomain.com/api/v1/clients/read.php?api_key=YOUR_KEY&limit=1"
+</code>
+  - **Expected Response**
+<code json>
+{
+  "success": "True",
+  "count": 1,
+  "data": [{"client_id": "123", "client_name": "Example Corp"}]
+}
+</code>
+===== API Overview =====
+**Source**: ITFlow official documentation at docs.itflow.org/api
+  * **Base URL**: ''/api/v1/{module}/{function}.php''
+  * **Version**: 1.0 (current)
+  * **Authentication**: API Key via query parameter ''?api_key=YOUR_KEY''
+  * **Response Format**: JSON with ''success'', ''message'', ''count'', ''data'' fields
+  * **Pagination**: Default 50 records, adjustable with ''limit'' and ''offset'' parameters
+  * **Content-Type**: ''application/json'' for POST requests
+  * **Character Encoding**: UTF-8 (utf8mb4 in database)
+==== Standard Response Format ====
+**Source**: ITFlow official API documentation
+<code json>
+{
+  "success": "True|False",
+  "message": "Descriptive status message",
+  "count": 50,
+  "data": [
+    {
+      "id": 123,
+      "field": "value"
+    }
+  ]
+}
+</code>
+===== Authentication & Security =====
+==== API Key Management ====
+  * **Generation**: Admin > API > New Key
+  * **Scoping Options**:
+    * **All Clients**: Full access to all client data
+    * **Specific Client**: Limited to single client (''client_id'' required)
+  * **Usage**: Query parameter ''?api_key=YOUR_KEY''
+  * **Security**: Keys stored encrypted in database
+==== Best Practices ====
+**Source**: MSP community recommendations and security standards
+  * **Rotate keys** regularly (monthly recommended)
+  * **Use client-scoped keys** for third-party integrations
+  * **Store keys securely** (environment variables, not code)
+  * **Monitor usage** via Apache/PHP logs
+  * **Use HTTPS only** for all API calls
+===== Currently Available Modules =====
+**Source**: ITFlow official API documentation confirms these modules have API support:
+==== Assets ''/api/v1/assets/'' ====
+**Purpose**: Computer and equipment inventory management
+**Source**: [[https://docs.itflow.org/assets|ITFlow Assets Documentation]]
+  * ''GET /read.php'' - List/get asset information
+  * ''POST /create.php'' - Create new asset record
+  * ''POST /update.php'' - Update existing asset
+  * ''POST /delete.php'' - Delete asset record
+**Complete Fields** (from ITFlow Assets API Documentation):
+<code json>
+{
+  "asset_id": 123,
+  "client_id": 456,
+  "asset_name": "Sample Laptop",
+  "asset_type": "Laptop",
+  "asset_make": "Dell",
+  "asset_model": "Optiplex",
+  "asset_serial": "XYZ",
+  "asset_os": "Win 10",
+  "asset_ip": "",
+  "asset_mac": "",
+  "asset_status": "Deployed",
+  "asset_purchase_date": "0000-00-00",
+  "asset_warranty_expire": "0000-00-00",
+  "install_date": "0000-00-00",
+  "asset_notes": "",
+  "asset_vendor_id": "",
+  "asset_location_id": "",
+  "asset_contact_id": "",
+  "asset_network_id": ""
+}
+</code>
+==== Certificates ''/api/v1/certificates/'' ====
+**Purpose**: SSL/TLS certificate management and expiration tracking
+**Source**: [[https://docs.itflow.org/certificates|ITFlow Certificates Documentation]]
+  * ''GET /read.php'' - List/get certificate information
+  * ''POST /create.php'' - Create certificate record
+  * ''POST /update.php'' - Update certificate details
+  * ''POST /delete.php'' - Delete certificate record
+**Complete Fields** (from ITFlow Certificates API Documentation):
+<code json>
+{
+  "certificate_id": 123,
+  "client_id": 456,
+  "certificate_name": "ITFlow Demo",
+  "certificate_domain": "demo.itflow.org",
+  "certificate_issued_date": "2024-01-01",
+  "certificate_expire_date": "2025-01-01",
+  "certificate_issuer": "Let's Encrypt",
+  "certificate_public_key": "[Certificate content]",
+  "certificate_notes": "Auto-renewal enabled"
+}
+</code>
+==== Clients ''/api/v1/clients/'' ====
+**Purpose**: Customer/company management
+**Source**: [[https://docs.itflow.org/clients|ITFlow Clients Documentation]]
+  * ''GET /read.php'' - List/get client information
+  * ''POST /create.php'' - Create new client
+  * ''POST /update.php'' - Update client details
+  * ''POST /delete.php'' - Delete client record
+**Complete Fields** (from ITFlow Clients API Documentation):
+<code json>
+{
+  "client_id": 111,
+  "client_lead": 0,
+  "client_name": "Let it burn Inc",
+  "client_type": "Safety and Fire",
+  "client_website": "example.com"
+}
+</code>
+<wrap em>Note: Full field list is partially documented. The API returns numbered keys alongside named keys in the response format.</wrap>
+==== Contacts ''/api/v1/contacts/'' ====
+**Purpose**: Individual contact management within client organizations
+**Source**: ITFlow official API documentation lists contacts as supported module
+  * ''GET /read.php'' - List/get contact information
+  * ''POST /create.php'' - Create new contact
+  * ''POST /update.php'' - Update contact details
+  * ''POST /delete.php'' - Delete contact record
+**Available Fields**: Contact table structure includes fields like ''contact_department'' as confirmed by GitHub Issue #458, but complete API field specification is not fully documented.
+==== Credentials ''/api/v1/credentials/'' ====
+**Purpose**: Password and login management (encrypted storage)
+**Source**: ITFlow official API documentation lists credentials (logins) as supported module
+  * ''GET /read.php'' - List/get credential information
+  * ''POST /create.php'' - Create new credential record
+  * ''POST /update.php'' - Update credential details
+  * ''POST /delete.php'' - Delete credential record
+**Available Fields**: Database migration scripts confirm ''login_folder_id'' field addition, but complete API field specification requires further documentation.
+==== Domains ''/api/v1/domains/'' ====
+**Purpose**: Domain name management and renewal tracking
+**Source**: [[https://docs.itflow.org/domains|ITFlow Domains Documentation]]
+  * ''GET /read.php'' - List/get domain information
+  * ''POST /create.php'' - Create domain record
+  * ''POST /update.php'' - Update domain details
+  * ''POST /delete.php'' - Delete domain record
+**Complete Fields** (from ITFlow Domains API Documentation):
+<code json>
+{
+  "domain_id": 123,
+  "client_id": 456,
+  "domain_name": "itflow.org",
+  "domain_registrar": "GoDaddy",
+  "domain_webhost": "SiteGround",
+  "domain_expire": "2025-03-15",
+  "domain_ip": "192.168.1.1",
+  "domain_name_servers": "ns1.example.com, ns2.example.com",
+  "domain_mail_servers": "mx1.example.com",
+  "domain_notes": "Auto-renewal enabled"
+}
+</code>
+==== Networks ''/api/v1/networks/'' ====
+**Purpose**: Network infrastructure documentation
+**Source**: ITFlow official API documentation lists networks as supported module
+  * ''GET /read.php'' - List/get network information
+  * ''POST /create.php'' - Create network record
+  * ''POST /update.php'' - Update network details
+  * ''POST /delete.php'' - Delete network record
+**Available Fields**: Database migration scripts show network interface relationships, but complete API field specification requires further documentation.
+==== Software ''/api/v1/software/'' ====
+**Purpose**: Software license and application tracking
+**Source**: ITFlow official API documentation lists software as supported module
+  * ''GET /read.php'' - List/get software information
+  * ''POST /create.php'' - Create software record
+  * ''POST /update.php'' - Update software details
+  * ''POST /delete.php'' - Delete software record
+**Status**: Module confirmed as available but dedicated documentation page not found. Database includes software table as confirmed by installation scripts.
+==== Tickets ''/api/v1/tickets/'' ====
+**Purpose**: Help desk and issue tracking
+**Source**: [[https://docs.itflow.org/tickets|ITFlow Tickets Documentation]]
+  * ''GET /read.php'' - List/get ticket information
+  * ''POST /create.php'' - Create new ticket
+  * ''POST /update.php'' - Update ticket details
+  * ''POST /delete.php'' - Delete ticket record
+**Complete Fields** (from ITFlow Tickets API Documentation):
+<code json>
+{
+  "ticket_id": 3,
+  "ticket_prefix": "TCK-",
+  "ticket_number": 3,
+  "ticket_category": null,
+  "ticket_subject": "Computer broken"
+}
+</code>
+<wrap em>Note: Full field list is partially documented. The API returns numbered keys alongside named keys in the response format.</wrap>
+===== Current API Capabilities =====
+==== Standard Operations (All Modules) ====
+  * **READ**: Retrieve single record or list of records
+  * **CREATE**: Add new records with validation (partial support)
+  * **UPDATE**: Modify existing records (partial support)
+  * **DELETE**: Remove records (partial support)
+==== Query Parameters (read.php endpoints) ====
+  * ''client_id'' - Filter by specific client
+  * ''limit'' - Number of records to return (default: 50)
+  * ''offset'' - Number of records to skip for pagination
+  * API key required on all requests
+==== Response Format (Standardized) ====
+<code json>
+{
+  "success": "True|False",
+  "message": "Descriptive message",
+  "count": 1,
+  "data": [
+    {
+      // Record data with both numbered and named keys
+    }
+  ]
+}
+</code>
+===== Current Authentication =====
+==== API Key Generation ====
+  - Navigate to Admin panel in ITFlow
+  - Click on API section
+  - Click **New Key** to generate
+  - Choose scope: specific client or all clients
+  - Copy generated key for use
+==== API Key Usage ====
+  * **Method**: Query parameter
+  * **Format**: ''?api_key=YOUR_API_KEY''
+  * **Scope**: Can be limited to specific client or all clients
+  * **Access**: Currently all-or-nothing permissions
+==== Security Features ====
+  * **Encrypted Storage**: API keys stored securely
+  * **Client Scoping**: Keys can be limited to specific clients
+  * **Access Logging**: API usage tracked in logs
+===== Current Limitations =====
+==== Missing CRUD Operations ====
+  * **UPDATE**: Limited support across modules
+  * **DELETE**: Limited support across modules
+  * **ARCHIVE**: Not implemented
+==== Missing Advanced Features ====
+  * **Bulk Operations**: No batch create/update/delete
+  * **Advanced Search**: No full-text search or complex filtering
+  * **Webhooks**: No real-time event notifications
+  * **File Upload**: No direct file management API
+  * **Relationships**: Limited cross-module data retrieval
+==== Missing Business Modules ====
+  * **Invoices/Billing**: No financial transaction APIs
+  * **Quotes**: No sales proposal management
+  * **Time Tracking**: No billable hour recording
+  * **Calendar**: No scheduling or appointment APIs
+  * **Reports**: No automated report generation
+==== Authentication Limitations ====
+  * **Granular Permissions**: No module-specific access control
+  * **OAuth**: Only API key authentication available
+===== API Usage Examples =====
+==== Get All Clients ====
+<code bash>
+GET /api/v1/clients/read.php?api_key=YOUR_KEY
+</code>
+==== Get Specific Asset ====
+<code bash>
+GET /api/v1/assets/read.php?api_key=YOUR_KEY&asset_id=123
+</code>
+==== Create New Ticket ====
+<code bash>
+POST /api/v1/tickets/create.php
+Content-Type: application/json
+{
+  "api_key": "YOUR_KEY",
+  "client_id": 456,
+  "ticket_subject": "Printer offline",
+  "ticket_details": "Office printer not responding",
+  "ticket_priority": "Medium"
+}
+</code>
+==== List Client Assets ====
+<code bash>
+GET /api/v1/assets/read.php?api_key=YOUR_KEY&client_id=456
+</code>
+===== Integration Capabilities =====
+==== What Works Today ====
+  * **Basic CRUD**: Create/read operations for core modules
+  * **Client Management**: Full customer database management
+  * **Asset Tracking**: Computer and equipment inventory
+  * **Ticket Creation**: Help desk ticket automation
+  * **Documentation**: Network, domain, certificate tracking
+==== What's Missing for Full Automation ====
+  * **Financial Operations**: No billing/invoicing automation
+  * **Real-time Events**: No webhook triggers for automation
+  * **Bulk Data Sync**: No efficient mass data operations
+  * **File Management**: No document upload/download APIs
+  * **Advanced Workflows**: No time tracking or scheduling APIs
+===== Error Handling & Troubleshooting =====
+==== Standard Error Codes ====
+**Source**: HTTP standard codes - ITFlow API observed behavior
+  * **200**: Success - Request completed successfully
+  * **400**: Bad Request - Invalid parameters or malformed request
+  * **401**: Unauthorized - Invalid or missing API key
+  * **403**: Forbidden - API key lacks required permissions
+  * **404**: Not Found - Endpoint or record doesn't exist
+  * **500**: Server Error - Internal ITFlow error
+==== Common Error Messages ====
+**Source**: Observed API responses
+<code json>
+{
+  "success": "False",
+  "message": "Invalid API key",
+  "count": 0,
+  "data": []
+}
+</code>
+==== Troubleshooting Steps ====
+**Source**: Community experience and [[https://docs.itflow.org/installation|ITFlow Installation Documentation]]
+  - **API Key Issues**
+    * Verify key is correct (copy/paste errors common)
+    * Check key scope (client-specific vs all clients)
+    * Confirm key hasn't been deactivated
+  - **Permission Errors**
+    * Add ''client_id'' parameter for scoped keys
+    * Verify client_id exists and is accessible
+  - **Server Errors**
+    * Check Apache/PHP error logs: ''/var/log/apache2/error.log''
+    * Verify ITFlow database connectivity
+    * Check PHP memory limits for large requests
+  - **Data Issues**
+    * Validate required fields for POST requests
+    * Check data types (strings, integers, dates)
+    * Verify foreign key relationships exist
+==== Debug Mode ====
+**Source**: ITFlow admin settings and [[https://docs.itflow.org/faq|ITFlow FAQ]]
+Enable PHP error reporting in ITFlow settings for detailed error messages during development.
+===== Integration Examples =====
+==== PowerShell Examples ====
+**Source**: [[https://github.com/itflow-org/itflow-api-powershell|ITFlow PowerShell Repository]]
+**List All Clients**:
+<code powershell>
+$apiKey = "YOUR-API-KEY"
+$baseUrl = "https://itflow.yourdomain.com"
+$uri = "$baseUrl/api/v1/clients/read.php?api_key=$apiKey"
+Invoke-RestMethod -Uri $uri | ConvertTo-Json
+</code>
+**Create New Asset**:
+<code powershell>
+$uri = "https://itflow.yourdomain.com/api/v1/assets/create.php"
+$body = @{
+    "api_key" = "YOUR-API-KEY"
+    "asset_name" = "Sample Laptop"
+    "asset_type" = "Laptop"
+    "asset_make" = "Dell"
+    "asset_model" = "Optiplex"
+    "client_id" = "1"
+} | ConvertTo-Json
+Invoke-RestMethod -Method Post -Uri $uri -Body $body -ContentType "application/json"
+</code>
+==== PHP Examples ====
+<code php>
+<?php
+$api_key = 'YOUR_API_KEY';
+$base_url = 'https://itflow.yourdomain.com/api/v1/';
+// Get clients
+$url = $base_url . 'clients/read.php?api_key=' . $api_key;
+$response = file_get_contents($url);
+$data = json_decode($response, true);
+print_r($data);
+?>
+</code>
+==== Python Examples ====
+<code python>
+import requests
+api_key = "YOUR_API_KEY"
+base_url = "https://itflow.yourdomain.com/api/v1/"
-Old API
+# Get all clients
+response = requests.get(f"{base_url}clients/read.php?api_key={api_key}")
+data = response.json()
+print(data)
-The legacy ITFlow API is accessed at /api.php. We are working on moving all functionality into the new API at /api/. The legacy API has the following features:
+# Create new ticket
+ticket_data = {
+    "api_key": api_key,
+    "client_id": 456,
+    "ticket_subject": "Network issue",
+    "ticket_details": "Unable to access shared drive",
+    "ticket_priority": "High"
+}
-    Caller ID lookup (Great for integrating with your phone system like FreePBX, and having your VOIP phone return the client's name thats calling in) - /api.php?api_key=[API_KEY]&cid=[PHONE_NUMBER] - Returns a name
+response = requests.post(f"{base_url}tickets/create.php", json=ticket_data)
-    XML Phonebook Download - /api.php?api_key=[API_KEY]&phonebook
+result = response.json()
-    Client Email (great for mailing lists) - /api.php?api_key=[API_KEY]&client_emails - Returns Client Name - Email Address
+print(result)
-    Account Balance for Client (can be integrated into multiple places for example in FreePBX Press 3 to check account balance, please enter your client ID your balance is) - /api.php?api_key=[API_KEY]&client_id=[CLIENT_ID] - Returns Account Balance
+</code>
-    Add new asset for a client - /api.php?api_key=[API_KEY]&client_id=ClientID&add_asset=Name&type=[Desktop|Laptop|Server]&make=Make&model=Model&serial=Serial&os=OS
-        Required: api_key, client_id, add_asset (name)

Tools

menus and quick search

quick search

site status

location indicator

Page Tools

meta data for this page

Differences