hfortix-forticare 0.5.160

FortiCare Asset Management API Client

hfortix-forticare

Python SDK for Fortinet FortiCare Asset Management V3 API.

Overview

hfortix-forticare provides a fully typed Python interface to the FortiCare Asset Management API, enabling programmatic access to:

• Product Management: Register, list, update, and decommission products
• License Management: Register, list, and download licenses
• Contract Management: View contract information
• Folder Management: Organize assets into folders
• Service Management: Register subscription services

Features

✨ Fully Typed - Complete type hints with TypedDict for request/response structures 📝 Auto-completion - IDE auto-completion for all parameters and return values 🔒 OAuth 2.0 - Built-in OAuth Bearer token authentication 🚀 Modern HTTP - HTTP/2 support via httpx 🎯 Explicit Parameters - All API parameters exposed as function arguments 📚 Rich Documentation - Comprehensive docstrings from Swagger specs

Installation

pip install hfortix-forticare

Quick Start

1. Obtain OAuth Token

First, create an API user through the IAM portal and obtain an OAuth token:

# Get token from FortiAuthenticator OAuth endpoint
# https://customerapiauth.fortinet.com/api/v1/oauth/token

2. Initialize Client

from hfortix_forticare import FortiCare

fcc = FortiCare(oauth_token="your_oauth_token_here")

3. Use the API

# List products with entitlements
products = fcc.api.products.list.post(
    serial_number="FGT*",
    status="Registered"
)

# Get product details
details = fcc.api.products.details.post(
    serial_number="FGT90D1234567890"
)

# Register a product
result = fcc.api.products.register.post(
    registration_units=[
        {
            "serialNumber": "FGT90D1234567890",
            "description": "My FortiGate",
            # ... other fields
        }
    ]
)

# List contracts
contracts = fcc.api.contracts.list.post()

# List licenses  
licenses = fcc.api.licenses.list.post()

# Manage folders
folders = fcc.api.folders.list.post()

# Always clean up when done
fcc.logout()

API Structure

The SDK mirrors the FortiCare Asset Management V3 API structure:

fcc.api.
  ├── products.
  │   ├── list          - List products with entitlements
  │   ├── register      - Register products and contracts
  │   ├── details       - Get product details
  │   ├── description   - Update product description
  │   ├── location      - Update product location
  │   ├── folder        - Update product folder
  │   ├── decommission  - Decommission products
  │   └── transfer      - Transfer products between accounts
  ├── licenses.
  │   ├── list          - List licenses
  │   ├── register      - Register a license
  │   └── download      - Download VM license file
  ├── contracts.
  │   └── list          - List contracts
  ├── folders.
  │   ├── list          - List asset folders
  │   ├── create        - Create new folder
  │   └── delete        - Delete folder
  └── services.
      └── register      - Register subscription service

Type Safety

All endpoints use TypedDict for request and response structures:

# IDE will show all available parameters
products = fcc.api.products.list.post(
    serial_number="FGT*",     # str
    expire_before="2024...",   # str (ISO 8601)
    status="Registered",       # str
    product_model="...",       # str  
    account_id=12345          # float
)

# Response is also typed
assert products['status'] == 0  # int
assert isinstance(products['message'], str)
assert isinstance(products['assets'], list)

Rate Limits

FortiCare Asset Management API enforces the following limits:

• 100 calls per minute
• 1000 calls per hour
• 10 errors per hour
• Batch operations: Max 10 units, max 5 errors per batch

Error Handling

try:
    result = fcc.api.products.list.post(serial_number="FGT*")
    
    if result['status'] == 0:
        print("Success!")
    else:
        print(f"API Error: {result['message']}")
        
except httpx.HTTPStatusError as e:
    print(f"HTTP Error: {e.response.status_code}")
except httpx.TimeoutException:
    print("Request timed out")
except httpx.RequestError as e:
    print(f"Network error: {e}")

Context Manager

Use as a context manager for automatic cleanup:

with FortiCare(oauth_token="...") as fcc:
    products = fcc.api.products.list.post(...)
    # ... use the client ...
# Automatically logged out

Configuration

fcc = FortiCare(
    oauth_token="your_token",
    base_url="https://support.fortinet.com",  # Default
    verify=True,                               # SSL verification
    max_retries=3,                            # Retry attempts
    connect_timeout=10.0,                     # Connection timeout (seconds)
    read_timeout=300.0                        # Read timeout (seconds)
)

Examples

See EXAMPLES.py for more comprehensive examples.

Development

Regenerating the SDK

If Fortinet updates the API, regenerate the SDK:

cd packages/forticare/dev/generator
python generate.py --clean

This will:

1. Parse updated Swagger JSON files
2. Generate all endpoint classes with type hints
3. Create .pyi stub files for IDE support
4. Generate category and main init.py files

Project Structure

packages/forticare/
├── src/
│   └── hfortix_forticare/
│       ├── __init__.py           # Main FortiCare client
│       └── api/
│           └── v3/
│               ├── __init__.py   # V3API class
│               ├── products/     # Product endpoints
│               ├── licenses/     # License endpoints
│               ├── contracts/    # Contract endpoints
│               ├── folders/      # Folder endpoints
│               └── services/     # Service endpoints
├── dev/
│   └── generator/
│       ├── generate.py           # Code generator
│       ├── parsers/              # Swagger parsers
│       ├── generators/           # Code generators
│       ├── templates/            # Code templates
│       └── swagger/              # Swagger JSON files
└── README.md

Requirements

• Python 3.10+
• httpx
• hfortix-core

License

Copyright © 2024 Fortinet, Inc.

Links

• FortiCare API Documentation
• OAuth Token Guide
• IAM Portal