Přeskočit obsah

API pro reporty

Týdenní reporty expirace certifikátů a tajemství — nastavení, ruční spuštění a náhled

Verze dokumentu: 1.0.41
Poslední aktualizace: 2026-04-26

Přehled

API pro reporty spravuje funkci týdenního reportu expirace. Report automaticky agreguje certifikáty a tajemství expirující v rámci nakonfigurovaného předstihu a doručuje report nakonfigurovaným příjemcům e-mailem.

API poskytuje čtyři endpointy:

Metoda Endpoint Popis
GET /api/v1/reports/settings Získání aktuálního nastavení reportu
PUT /api/v1/reports/settings Aktualizace nastavení reportu
POST /api/v1/reports/trigger Ruční spuštění doručení reportu
GET /api/v1/reports/preview Náhled obsahu reportu bez odeslání

Získání nastavení reportu

Vrátí aktuální konfiguraci příjemců týdenního reportu expirace.

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

Odpověď 200 OK

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

Pole odpovědi

Pole Typ Popis
recipients pole řetězců E-mailové adresy, které aktuálně dostávají týdenní report

Aktualizace nastavení reportu

Nahradí celý seznam příjemců. Odešlete prázdné pole pro zakázání doručování reportu.

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"
  ]
}

Pole požadavku

Pole Typ Povinné Popis
recipients pole řetězců ✅ Seznam e-mailových adres pro příjem reportu (max 10). Každá adresa musí být ve validním e-mailovém formátu. Odešlete [] pro zakázání doručování e-mailem.

Odpověď 200 OK

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

Plánování

Report je automaticky doručován každé pondělí v čase nakonfigurovaném při nastavení platformy. Tento endpoint spravuje pouze příjemce — plán je řízen konfigurací platformy.

Spuštění reportu

Ručně spustí okamžité doručení reportu všem nakonfigurovaným příjemcům. Vhodné pro testování konfigurace příjemců nebo pro mimořádné doručení mimo pravidelný plán.

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

Tělo požadavku není potřeba.

Odpověď 200 OK

{
  "status": "triggered"
}

Chování doručení

Ruční spuštění používá stejnou logiku generování reportu jako plánované doručení. Report zahrnuje položky expirující v rámci standardního předstihového okna. Pokud nejsou nakonfigurovány žádní příjemci, požadavek vrátí 200 OK se stavem "status": "triggered", ale žádný e-mail se neodešle.

Náhled reportu

Vrátí aktuální obsah reportu bez odeslání jakýchkoli e-mailů. Použijte pro kontrolu toho, co by bylo zahrnuto v dalším plánovaném doručení.

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

Odpověď 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"
    }
  ]
}

Pole odpovědi

Pole Typ Popis
generated_at string (ISO 8601) Časové razítko generování tohoto náhledu
total_certificates integer Počet certifikátů expirujících v reportovacím okně
total_secrets integer Počet tajemství expirujících v reportovacím okně
expiring_certificates pole Seznam certifikátů expirujících v rámci předstihového okna
expiring_secrets pole Seznam tajemství expirujících v rámci předstihového okna

Objekt expiring_certificates

Pole Typ Popis
common_name string Common Name (CN) certifikátu
expires_at string (ISO 8601) Datum expirace certifikátu
days_remaining integer Počet dní do expirace v době generování náhledu
issuer string Název vydávající CA
serial_number string Sériové číslo certifikátu
auto_renew boolean Zda je pro certifikát nakonfigurováno automatické obnovení
project_name string Název projektu vlastnícího certifikát
environment string Prostředí certifikátu

Objekt expiring_secrets

Pole Typ Popis
name string Název klíče tajemství
expires_at string (ISO 8601) Datum expirace tajemství
days_remaining integer Počet dní do expirace v době generování náhledu
type string Typ tajemství (např. api_key, password, certificate)
project_name string Název projektu vlastnícího tajemství
environment string Prostředí tajemství

Chybové odpovědi

HTTP Status Význam
400 Bad Request Neplatné tělo požadavku — např. neplatný formát e-mailové adresy nebo více než 10 příjemců
401 Unauthorized Chybějící nebo neplatný bearer token
403 Forbidden Nedostatečná oprávnění role (pro aktualizaci nastavení nebo spuštění reportu je vyžadována role administrátora)

Viz také