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.61
Poslední aktualizace: 2026-11-09

Přehled

API pro reporty spravuje týdenní report expirace. Každá organizace má vlastní e-mailové příjemce a dostává jen report své organizace: certifikáty a tajemství svých projektů, které expirují v příštích 60 dnech. Report jde také do notifikačních kanálů organizace s povoleným reportem (Slack, Teams, webhook, Jira). Certifikáty bez projektu nepatří žádné organizaci, a proto nejsou v týdenním reportu žádné organizace; aby se v reportu objevily, přiřaďte je do projektu.

Metoda Endpoint Popis Oprávnění
GET /api/v1/organizations/{id}/reports/settings Příjemci organizace report:read v organizaci
PUT /api/v1/organizations/{id}/reports/settings Nahrazení příjemců organizace report:write v organizaci
POST /api/v1/organizations/{id}/reports/trigger Okamžité odeslání reportu organizace report:write v organizaci
GET /api/v1/organizations/{id}/reports/preview Náhled reportu organizace report:read v organizaci
GET /api/v1/reports/settings Dřívější příjemci na úrovni instance (nedostávají nic) globální report:read
PUT /api/v1/reports/settings Změna nebo smazání příjemců na úrovni instance globální report:write
POST /api/v1/reports/trigger Okamžité odeslání reportu každé organizaci globální report:write
GET /api/v1/reports/preview Náhled položek všech organizací a projektů, které volající vidí report:read

„V organizaci“ znamená organizační roli v dané organizaci nebo globální roli; projektová role nestačí.

Získání nastavení reportu organizace

Vrátí příjemce týdenního reportu organizace.

GET /api/v1/organizations/{id}/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é dostávají týdenní report této organizace

Aktualizace nastavení reportu organizace

Nahradí celý seznam příjemců organizace. Prázdné pole zastaví doručování e-mailem. Změna se zapíše do auditu jako REPORT_RECIPIENTS_UPDATED (počet příjemců, ne adresy).

PUT /api/v1/organizations/{id}/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

{
  "message": "Settings updated"
}

Plánování

Každé pondělí v 7:00 (Europe/Prague) se report každé organizace odešle jejím příjemcům a kanálům s povoleným reportem. Tento endpoint spravuje pouze příjemce.

Spuštění reportu organizace

Odešle report organizace hned jejím příjemcům a kanálům s povoleným reportem, se stejným obsahem jako plánované doručení.

POST /api/v1/organizations/{id}/reports/trigger HTTP/1.1
Authorization: Bearer <token>

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

Odpověď 200 OK

{
  "message": "Report triggered successfully"
}

Chování doručení

Bez příjemců a kanálů s povoleným reportem se nic neodešle a požadavek přesto vrátí 200 OK. Když některý příjemce nebo kanál není dosažitelný, ostatní report dostanou a požadavek vrátí 500 s neúspěšnými doručeními v details.

Příjemci na úrovni instance

Před příjemci po organizacích existoval jeden seznam příjemců pro celou instanci. Při upgradu instance s jedinou organizací tento seznam přesunula k ní. Při více organizacích seznam zůstane jako příjemci na úrovni instance, kteří nedostávají žádný report, aby se report jedné organizace nedostal k lidem jiné. Globální administrátor je uvidí přes GET /api/v1/reports/settings, přidá je ke správným organizacím a pak je smaže přes PUT /api/v1/reports/settings s {"recipients": []}. Záložka System Outputs → Weekly Expiry Report je globálnímu administrátorovi ukáže s tlačítkem Clear.

POST /api/v1/reports/trigger (globální role) pošle každé organizaci její vlastní report, stejně jako pondělní běh.

Náhled reportu

Vrátí obsah reportu organizace bez odeslání: co by její příjemci dostali příště. GET /api/v1/reports/preview vrací stejný tvar pro všechny organizace a projekty, které volající vidí.

GET /api/v1/organizations/{id}/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 Volající nemá v organizaci organizační ani globální roli s report:read/report:write (projektová role nestačí), nebo nemá globální roli pro /api/v1/reports/settings a /trigger
404 Not Found Organizace neexistuje

Viz také