Skip to content

Reports API

Weekly Certificate and Secret Expiry Reports — Settings, Trigger, and Preview

Document Version: 1.0.41
Last Updated: 2026-04-26

Overview

The Reports API manages the weekly expiry report feature. The report automatically aggregates certificates and secrets that are expiring within the configured lookahead window and delivers the report to the configured recipient list by email.

The API provides four endpoints:

Method Endpoint Description
GET /api/v1/reports/settings Get current report settings
PUT /api/v1/reports/settings Update report settings
POST /api/v1/reports/trigger Manually trigger a report delivery
GET /api/v1/reports/preview Preview report content without sending

Get Report Settings

Returns the current recipient configuration for the weekly expiry report.

GET /api/v1/reports/settings HTTP/1.1
Authorization: Bearer <token>

Response 200 OK

{
  "recipients": [
    "security@example.com",
    "ops-team@example.com"
  ]
}

Response Fields

Field Type Description
recipients array of strings Email addresses that currently receive the weekly report

Update Report Settings

Replaces the full recipient list. Send an empty array to disable report delivery.

PUT /api/v1/reports/settings HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

{
  "recipients": [
    "security@example.com",
    "ops-team@example.com",
    "ciso@example.com"
  ]
}

Request Fields

Field Type Required Description
recipients array of strings ✅ List of email addresses to receive the report (max 10). Each address must be a valid email format. Send [] to disable email delivery.

Response 200 OK

{
  "recipients": [
    "security@example.com",
    "ops-team@example.com",
    "ciso@example.com"
  ]
}

Scheduling

The report is delivered automatically every Monday at the time configured during platform setup. This endpoint only manages recipients — the schedule is controlled via platform configuration.

Trigger Report

Manually triggers an immediate report delivery to all configured recipients. Useful for testing recipient configuration or for on-demand distribution outside the regular schedule.

POST /api/v1/reports/trigger HTTP/1.1
Authorization: Bearer <token>

No request body is required.

Response 200 OK

{
  "status": "triggered"
}

Delivery Behavior

The trigger runs the same report generation logic as the scheduled delivery. The report includes items expiring within the standard lookahead window. If no recipients are configured, the request returns 200 OK with "status": "triggered" but no email is sent.

Preview Report

Returns the current report content without sending any emails. Use this to inspect what would be included in the next report delivery.

GET /api/v1/reports/preview HTTP/1.1
Authorization: Bearer <token>

Response 200 OK

{
  "generated_at": "2026-04-26T10:00:00Z",
  "total_certificates": 3,
  "total_secrets": 1,
  "expiring_certificates": [
    {
      "common_name": "api.example.com",
      "expires_at": "2026-05-10T00:00:00Z",
      "days_remaining": 14,
      "issuer": "MazeVault Internal CA",
      "serial_number": "0a:1b:2c:3d:4e:5f",
      "auto_renew": true,
      "project_name": "Backend Services",
      "environment": "production"
    },
    {
      "common_name": "internal.corp.example.com",
      "expires_at": "2026-05-20T00:00:00Z",
      "days_remaining": 24,
      "issuer": "MazeVault Internal CA",
      "serial_number": "ff:ee:dd:cc:bb:aa",
      "auto_renew": false,
      "project_name": "Internal Tools",
      "environment": "staging"
    }
  ],
  "expiring_secrets": [
    {
      "name": "stripe-api-key",
      "expires_at": "2026-05-05T00:00:00Z",
      "days_remaining": 9,
      "type": "api_key",
      "project_name": "Payment Service",
      "environment": "production"
    }
  ]
}

Response Fields

Field Type Description
generated_at string (ISO 8601) Timestamp when this preview was generated
total_certificates integer Number of expiring certificates included in the report
total_secrets integer Number of expiring secrets included in the report
expiring_certificates array List of certificates expiring within the lookahead window
expiring_secrets array List of secrets expiring within the lookahead window

expiring_certificates Object

Field Type Description
common_name string Certificate Common Name (CN)
expires_at string (ISO 8601) Certificate expiry timestamp
days_remaining integer Days until expiry at the time the preview was generated
issuer string Issuing CA name
serial_number string Certificate serial number
auto_renew boolean Whether automatic renewal is configured for this certificate
project_name string Name of the project that owns the certificate
environment string Environment scope of the certificate

expiring_secrets Object

Field Type Description
name string Secret key name
expires_at string (ISO 8601) Secret expiry timestamp
days_remaining integer Days until expiry at the time the preview was generated
type string Secret type (e.g., api_key, password, certificate)
project_name string Name of the project that owns the secret
environment string Environment scope of the secret

Error Responses

HTTP Status Meaning
400 Bad Request Invalid request body — e.g., invalid email address format or more than 10 recipients
401 Unauthorized Missing or invalid bearer token
403 Forbidden Insufficient role permissions (admin role required to update settings or trigger reports)