API Documentation

Overview

This API provides programmatic access to the ISP Management System. All API endpoints require authentication using API keys, which can be generated from the user management interface.

Authentication

All API requests must include a valid API key in the request headers. API keys are generated per user and can be managed from the user profile page.

Authentication Methods

You can provide your API key using one of the following methods:

X-API-Key: your-api-key-here

Authorization: Bearer your-api-key-here

Getting Your API Key

1. Log into the application
2. Navigate to Users → Select your user → Click View
3. Scroll to the API Keys Management section
4. Click Create API Key
5. Important: Copy the API key immediately - it will only be shown once!

API Key Security

• Never share your API key publicly or commit it to version control
• API keys are hashed and stored securely in the database
• Each API key tracks its last usage timestamp
• API keys can be deleted at any time from the user profile
• If an API key is compromised, delete it immediately and create a new one

Authentication Errors

Standard Response Format

All API responses follow a consistent structure for easy parsing and error handling.

Success Response

{
    "success": true,
    "message": "Operation successful",
    "data": {
        // Response data here
    }
}

Error Response

{
    "success": false,
    "message": "Error message describing what went wrong",
    "errors": {
        // Validation errors (if applicable)
    }
}

HTTP Status Codes

Create a new customer in the system.

Request Headers

Request Body

{
    "first_name": "John",
    "last_name": "Doe",
    "email": "[email protected]",
    "password": "SecurePassword123!",
    "phone": "+1234567890",
    "address": "123 Main Street",
    "city": "New York",
    "country": "United States",
    "postal_code": "10001",
    "user_group_id": 1,
    "organization_ids": [1, 2],
    "billing_method": "prorata",
    "billing_day": 15,
    "auto_suspension": true,
    "suspend_after_days": 7
}

Field Descriptions

*Billing fields are required only if billing is enabled in system settings.

Success Response (201 Created)

{
    "success": true,
    "message": "Customer created successfully",
    "data": {
        "customer": {
            "id": 123,
            "first_name": "John",
            "last_name": "Doe",
            "full_name": "John Doe",
            "email": "[email protected]",
            "phone": "+1234567890",
            "address": "123 Main Street",
            "city": "New York",
            "country": "United States",
            "postal_code": "10001",
            "user_group_id": 1,
            "billing_method": "prorata",
            "billing_day": 15,
            "auto_suspension": true,
            "suspend_after_days": 7,
            "organizations": [
                {
                    "id": 1,
                    "name": "Organization Name"
                }
            ],
            "created_at": "2024-01-15T10:30:00.000000Z",
            "updated_at": "2024-01-15T10:30:00.000000Z"
        }
    }
}

Error Response Examples

{
    "success": false,
    "message": "Validation failed",
    "errors": {
        "first_name": [
            "The first name field is required."
        ],
        "phone": [
            "A customer with this phone number already exists."
        ],
        "password": [
            "The password must be at least 8 characters.",
            "The password must contain at least one uppercase letter."
        ]
    }
}

{
    "success": false,
    "message": "Invalid API key",
    "error": "The provided API key is invalid or does not exist."
}

Code Examples

curl -X POST https://your-domain.com/api/v1/customers \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key-here" \
  -d '{
    "first_name": "John",
    "last_name": "Doe",
    "email": "[email protected]",
    "password": "SecurePassword123!",
    "phone": "+1234567890",
    "city": "New York",
    "country": "United States"
  }'

use GuzzleHttp\Client;

$client = new Client([
    'base_uri' => 'https://your-domain.com/api/v1/',
    'headers' => [
        'X-API-Key' => 'your-api-key-here',
        'Content-Type' => 'application/json'
    ]
]);

try {
    $response = $client->post('customers', [
        'json' => [
            'first_name' => 'John',
            'last_name' => 'Doe',
            'email' => '[email protected]',
            'password' => 'SecurePassword123!',
            'phone' => '+1234567890'
        ]
    ]);

    $data = json_decode($response->getBody(), true);
    
    if ($data['success']) {
        echo "Customer created: " . $data['data']['customer']['full_name'];
    }
} catch (\Exception $e) {
    echo "Error: " . $e->getMessage();
}

const createCustomer = async (customerData) => {
    const response = await fetch('https://your-domain.com/api/v1/customers', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'X-API-Key': 'your-api-key-here'
        },
        body: JSON.stringify(customerData)
    });

    const data = await response.json();
    
    if (data.success) {
        console.log('Customer created:', data.data.customer);
        return data.data.customer;
    } else {
        console.error('Error:', data.message);
        throw new Error(data.message);
    }
};

// Usage
createCustomer({
    first_name: 'John',
    last_name: 'Doe',
    email: '[email protected]',
    password: 'SecurePassword123!',
    phone: '+1234567890'
});

import requests

url = 'https://your-domain.com/api/v1/customers'
headers = {
    'Content-Type': 'application/json',
    'X-API-Key': 'your-api-key-here'
}
data = {
    'first_name': 'John',
    'last_name': 'Doe',
    'email': '[email protected]',
    'password': 'SecurePassword123!',
    'phone': '+1234567890'
}

response = requests.post(url, json=data, headers=headers)
result = response.json()

if result['success']:
    print(f"Customer created: {result['data']['customer']['full_name']}")
else:
    print(f"Error: {result['message']}")

Rate Limiting

API requests are rate-limited to prevent abuse. The current rate limit is:

Rate Limit Headers

Every API response includes rate limit information in the headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1640995200

Error Handling

Best Practices

1. Always check the success field in the response to determine if the request was successful
2. Handle validation errors by checking the errors object in error responses
3. Implement retry logic for 5xx server errors
4. Log API errors for debugging and monitoring
5. Respect rate limits by implementing exponential backoff

Password Policy

The password must meet the following requirements (configurable in system settings):

• Minimum length (typically 8 characters)
• At least one uppercase letter
• At least one lowercase letter
• At least one number
• At least one special character

Check the /api/security-settings endpoint for current password policy requirements.

Changelog

Future Endpoints

The following endpoints are planned for future releases:

• GET /api/v1/customers - List customers
• GET /api/v1/customers/{id} - Get customer details
• PUT /api/v1/customers/{id} - Update customer
• DELETE /api/v1/customers/{id} - Delete customer
• POST /api/v1/subscriptions - Create subscription
• GET /api/v1/subscriptions - List subscriptions
• And more...