API - Certificate Auto-Renewal

This section details the API endpoints for managing automated certificate renewal, offering programmatic control over the auto-renewal process, configuration, and individual certificate settings. These endpoints are secured using auth:sanctum and require the manage-certificates permission.

Key Functionalities

Get Auto-Renewal Statistics

  • Endpoint: GET /api/v1/auto-renewal/statistics
  • Description: Retrieves aggregated statistics related to the certificate auto-renewal process, providing insights into its performance and status.

Health Check

  • Endpoint: GET /api/v1/auto-renewal/health
  • Description: Returns the current health status of the auto-renewal service, indicating its operational state.

Enable Auto-Renewal for a Certificate

  • Endpoint: POST /api/v1/auto-renewal/certificates/{certificate}/enable
  • Description: Activates auto-renewal for a specific certificate, with optional parameters to customize its renewal behavior.
  • Parameters (Optional):
    • renewal_threshold_days: Integer (1-90), specifies how many days before expiration to attempt renewal for this specific certificate.
    • max_renewal_attempts: Integer (1-10), sets the maximum number of renewal attempts for this certificate.
    • notification_email: Email address for renewal notifications specific to this certificate.
  • Response: Returns the updated certificate details, including its auto_renew status and auto_renewal_config.

Disable Auto-Renewal for a Certificate

  • Endpoint: POST /api/v1/auto-renewal/certificates/{certificate}/disable
  • Description: Deactivates auto-renewal for a specific certificate.
  • Parameters (Optional):
    • reason: String (max 255 chars), provides a reason for disabling auto-renewal.
  • Response: Returns the updated certificate details, including its auto_renew status and auto_renewal_config.

Get Eligible Certificates

  • Endpoint: GET /api/v1/auto-renewal/eligible-certificates
  • Description: Retrieves a list of certificates that are currently eligible for auto-renewal based on their expiration date and auto-renewal status.
  • Parameters (Optional):
    • threshold_days: Integer, overrides the default renewal threshold to filter certificates expiring within a custom number of days.
  • Response: Returns a list of eligible certificates with details such as common name, type, serial number, CA name, expiration date, and days until expiry.

Trigger Manual Renewal Process

  • Endpoint: POST /api/v1/auto-renewal/trigger
  • Description: Allows for the manual initiation of the auto-renewal process.
  • Parameters:
    • dry_run: Boolean (optional, defaults to false), if true, simulates the renewal process without making actual changes.
    • certificate_ids: Array of integers (optional), specifies a list of certificate IDs for selective renewal. Note: Selective renewal by certificate_ids is currently not implemented.
  • Response: For dry_run, it returns the number of certificates that would be processed. For actual runs, it returns the results of the auto-renewal process.

Get Auto-Renewal Configuration

  • Endpoint: GET /api/v1/auto-renewal/configuration
  • Description: Retrieves the current global auto-renewal configuration settings.
  • Response: Returns a JSON object containing various configuration parameters, including:
    • auto_renew (global enable/disable status).
    • default_threshold_days.
    • max_validity_days and default_validity_days for certificates.
    • bcrypt_rounds for hashing.
    • notification_settings (mail and queue enabled status).
    • supported_certificate_types.

Inferred Specifications

  • API-Driven Automation: The auto-renewal feature is fully exposed via a RESTful API, enabling external systems and scripts to manage certificate renewals programmatically.
  • Granular Per-Certificate Control: Beyond global settings, individual certificates can have their auto-renewal behavior customized with specific thresholds, retry attempts, and notification preferences.
  • Simulation Mode: The dry_run option for triggering renewals is a valuable tool for testing and planning, allowing administrators to preview the impact of a renewal run without affecting production certificates.
  • Explicit Feature Limitations: The API clearly indicates that selective renewal by certificate_ids is a planned but not yet implemented feature, managing expectations.
  • Comprehensive Configuration Exposure: The getConfiguration endpoint provides a detailed view of the system's auto-renewal parameters, which is useful for auditing and integration purposes.
  • Security: All API interactions are protected by auth:sanctum middleware and require the manage-certificates permission, ensuring only authorized users can manage auto-renewal settings.

Vous n'avez pas envie de la manager ?

Découvrir notre offre PKI As A Service