Skip to main content

Certificates API Reference

The Certificates API provides programmatic access to SSL/TLS certificate discovery, monitoring, and management across your OT infrastructure. This API enables automation of certificate tracking, expiration monitoring, and security assessment.

Authentication​

All Certificate API endpoints require authentication via API token:

Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

Certificate Discovery​

List Site Certificates​

GET /api/v1/sites/{site_id}/certificates

Query Parameters:

  • status (optional): Filter by certificate status (active, expiring, expired)
  • expiringWithin (optional): Days until expiration (e.g., 30, 60, 90)
  • deviceId (optional): Filter by specific device identifier
  • protocol (optional): Filter by protocol (https, imaps, pop3s, smtps)
  • port (optional): Filter by specific port number
  • selfSigned (optional): Filter self-signed certificates (true, false)
  • weakKey (optional): Filter certificates with weak keys (true, false)
  • limit (optional): Maximum number of results (default: 50)
  • offset (optional): Pagination offset (default: 0)

Response:

{
  "certificates": [
    {
      "id": "cert_abc123",
      "site_id": "site_456",
      "hostname": "hmi-01.plant.local",
      "ip_address": "192.168.1.100",
      "port": 443,
      "protocol": "https",
      "subject": {
        "common_name": "hmi-01.plant.local",
        "organization": "Manufacturing Corp",
        "country": "US"
      },
      "issuer": {
        "common_name": "Internal CA",
        "organization": "Manufacturing Corp",
        "country": "US"
      },
      "san_entries": [
        "hmi-01.plant.local",
        "hmi-01",
        "192.168.1.100"
      ],
      "valid_from": "2024-01-01T00:00:00Z",
      "valid_to": "2025-01-01T00:00:00Z",
      "days_until_expiry": 245,
      "status": "active",
      "key_algorithm": "RSA",
      "key_size": 2048,
      "signature_algorithm": "SHA256withRSA",
      "is_self_signed": false,
      "is_weak_key": false,
      "chain_valid": true,
      "last_scanned": "2024-01-21T10:30:00Z",
      "device_id": "device_789"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

Get Organization Certificate Summary​

GET /api/v1/certificates/summary

Query Parameters:

  • site_id (optional): Filter by specific site
  • timeframe (optional): Summary timeframe (30d, 90d, 1y)

Response:

{
  "summary": {
    "total_certificates": 156,
    "active_certificates": 142,
    "expiring_certificates": 12,
    "expired_certificates": 2,
    "health_score": 87.5,
    "by_status": {
      "active": 142,
      "expiring": 12,
      "expired": 2
    },
    "by_site": [
      {
        "site_id": "site_456",
        "site_name": "Plant A",
        "certificate_count": 89,
        "health_score": 91.2
      },
      {
        "site_id": "site_457",
        "site_name": "Plant B", 
        "certificate_count": 67,
        "health_score": 82.1
      }
    ],
    "by_protocol": {
      "https": 134,
      "imaps": 12,
      "smtps": 8,
      "pop3s": 2
    },
    "security_risks": {
      "self_signed": 15,
      "weak_keys": 3,
      "deprecated_tls": 8,
      "chain_invalid": 1
    }
  }
}

Certificate Management​

Get Certificate Details​

GET /api/v1/certificates/{certificate_id}

Response:

{
  "id": "cert_abc123",
  "site_id": "site_456",
  "hostname": "hmi-01.plant.local",
  "ip_address": "192.168.1.100",
  "port": 443,
  "protocol": "https",
  "subject": {
    "common_name": "hmi-01.plant.local",
    "organization": "Manufacturing Corp",
    "organizational_unit": "Plant Operations",
    "locality": "Chicago",
    "state": "IL",
    "country": "US"
  },
  "issuer": {
    "common_name": "Internal CA",
    "organization": "Manufacturing Corp",
    "country": "US"
  },
  "san_entries": [
    "hmi-01.plant.local",
    "hmi-01",
    "192.168.1.100"
  ],
  "valid_from": "2024-01-01T00:00:00Z",
  "valid_to": "2025-01-01T00:00:00Z",
  "days_until_expiry": 245,
  "status": "active",
  "key_algorithm": "RSA",
  "key_size": 2048,
  "signature_algorithm": "SHA256withRSA",
  "serial_number": "12:34:56:78:9A:BC:DE:F0",
  "fingerprint_sha1": "A1:B2:C3:D4:E5:F6:07:18:29:3A:4B:5C:6D:7E:8F:90:A1:B2:C3:D4",
  "fingerprint_sha256": "1A:2B:3C:4D:5E:6F:70:81:92:A3:B4:C5:D6:E7:F8:09:1A:2B:3C:4D:5E:6F:70:81:92:A3:B4:C5:D6:E7:F8:09:1A",
  "certificate_chain": [
    {
      "level": 0,
      "subject": "CN=hmi-01.plant.local,O=Manufacturing Corp,C=US",
      "issuer": "CN=Internal CA,O=Manufacturing Corp,C=US"
    },
    {
      "level": 1,
      "subject": "CN=Internal CA,O=Manufacturing Corp,C=US", 
      "issuer": "CN=Root CA,O=Manufacturing Corp,C=US"
    }
  ],
  "is_self_signed": false,
  "is_weak_key": false,
  "chain_valid": true,
  "security_warnings": [],
  "device_correlation": {
    "device_id": "device_789",
    "device_name": "HMI-01 Operator Station",
    "device_type": "hmi"
  },
  "scan_history": [
    {
      "scanned_at": "2024-01-21T10:30:00Z",
      "status": "active",
      "changes_detected": false
    }
  ]
}

Add Manual Certificate​

POST /api/v1/sites/{site_id}/certificates

Request Body:

{
  "hostname": "new-hmi.plant.local",
  "ip_address": "192.168.1.200",
  "port": 443,
  "protocol": "https",
  "description": "New HMI system certificate",
  "monitoring_enabled": true
}

Response:

{
  "id": "cert_def456",
  "hostname": "new-hmi.plant.local",
  "ip_address": "192.168.1.200",
  "port": 443,
  "status": "pending_scan",
  "created_at": "2024-01-21T11:00:00Z",
  "next_scan": "2024-01-21T11:05:00Z"
}

Update Certificate​

PATCH /api/v1/certificates/{certificate_id}

Request Body:

{
  "description": "Updated description",
  "monitoring_enabled": false,
  "alert_suppressed": true,
  "suppression_reason": "Planned replacement scheduled",
  "suppression_until": "2024-02-01T00:00:00Z"
}

Response:

{
  "id": "cert_abc123",
  "description": "Updated description",
  "monitoring_enabled": false,
  "alert_suppressed": true,
  "suppression_reason": "Planned replacement scheduled",
  "suppression_until": "2024-02-01T00:00:00Z",
  "updated_at": "2024-01-21T11:15:00Z"
}

Delete Certificate​

DELETE /api/v1/certificates/{certificate_id}

Response:

{
  "message": "Certificate deleted successfully",
  "id": "cert_abc123"
}

Certificate Scanning​

Trigger Site Certificate Scan​

POST /api/v1/sites/{site_id}/certificates/scan

Request Body:

{
  "scan_type": "discovery",
  "target_ranges": [
    "192.168.1.0/24",
    "10.0.1.0/24"
  ],
  "ports": [443, 993, 995, 465, 8443],
  "timeout_seconds": 30,
  "concurrent_scans": 10
}

Response:

{
  "scan_id": "scan_789",
  "status": "initiated",
  "scan_type": "discovery",
  "target_count": 512,
  "estimated_duration": "00:15:00",
  "started_at": "2024-01-21T11:00:00Z"
}

Get Scan History​

GET /api/v1/sites/{site_id}/certificates/scan-history

Query Parameters:

  • scan_type (optional): Filter by scan type (discovery, targeted, scheduled)
  • status (optional): Filter by scan status (completed, running, failed)
  • limit (optional): Maximum number of results (default: 50)

Response:

{
  "scans": [
    {
      "scan_id": "scan_789",
      "scan_type": "discovery",
      "status": "completed",
      "started_at": "2024-01-21T11:00:00Z",
      "completed_at": "2024-01-21T11:12:00Z",
      "duration": "00:12:00",
      "targets_scanned": 512,
      "certificates_found": 15,
      "new_certificates": 3,
      "updated_certificates": 2
    }
  ]
}

Error Handling​

Standard Error Response​

{
  "error": {
    "code": "CERTIFICATE_NOT_FOUND",
    "message": "Certificate with ID cert_abc123 not found",
    "details": {
      "certificate_id": "cert_abc123",
      "site_id": "site_456"
    }
  }
}

Common Error Codes​

  • CERTIFICATE_NOT_FOUND: Certificate ID does not exist
  • SITE_NOT_FOUND: Site ID does not exist
  • INVALID_IP_ADDRESS: IP address format invalid
  • INVALID_PORT_NUMBER: Port number out of valid range
  • SCAN_IN_PROGRESS: Cannot start scan while another is running
  • SCAN_QUOTA_EXCEEDED: Too many concurrent scans
  • INSUFFICIENT_PERMISSIONS: API token lacks required permissions
  • CERTIFICATE_UNREACHABLE: Cannot connect to certificate endpoint

Rate Limiting​

The Certificates API implements rate limiting to ensure fair usage:

  • Discovery Scans: Maximum 5 concurrent scans per organization
  • API Requests: 1000 requests per hour per API token
  • Bulk Operations: Maximum 100 certificates per bulk request

Rate limit headers are included in all responses:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 995
X-RateLimit-Reset: 1642770000