====== API ======


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 **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 =====

  * assets
  * certificates
  * clients
  * contacts
  * credentials (logins)
  * domains
  * networks
  * software
  * tickets


===== API Functions =====

  * read
  * create //(partial)//
  * update //(partial)//
  * delete //(partial)//


  * //We may also add archive//

===== Request Methods =====

  * GET - Retrieving (READ) data
  * POST - Inserting (CREATE), Updating (UPDATE) or Deleting (DELETE) data

==== Data Returned ====

  * Success - True/False
  * Message - Failure info / Helpful debug info
  * Count - Count of rows affected/returned
  * Data - The data requested/created/changed


==== Notes ====

  * 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
  * 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 [[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/"

# Get all clients
response = requests.get(f"{base_url}clients/read.php?api_key={api_key}")
data = response.json()
print(data)

# 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"
}

response = requests.post(f"{base_url}tickets/create.php", json=ticket_data)
result = response.json()
print(result)
</code>