API pro certifikáty¶

Správa životního cyklu certifikátů — žádost, vydání, odvolání, obnovení, import/export

Verze dokumentu: 1.2.0
Poslední aktualizace: 2026-08-23

Přehled endpointů¶

Metoda	Endpoint	Popis
POST	`/api/v1/certificates/csr`	Odeslat žádost o podpis certifikátu (CSR)
GET	`/api/v1/certificates`	Zobrazit certifikáty
GET	`/api/v1/certificates/:id`	Získat detail certifikátu
POST	`/api/v1/certificates/:id/approve`	Schválit čekající CSR
POST	`/api/v1/certificates/:id/reject`	Zamítnout čekající CSR
POST	`/api/v1/certificates/:id/revoke`	Odvolat certifikát
POST	`/api/v1/certificates/:id/unrevoke`	Zrušit odvolání certifikátu
GET	`/api/v1/certificates/:id/export`	Exportovat certifikát
POST	`/api/v1/certificates/import`	Importovat certifikát
POST	`/api/v1/certificates/import/file`	Import souboru (PEM/DER/PFX)
POST	`/api/v1/certificates/import/preview`	Náhled importu
POST	`/api/v1/certificates/import/bulk`	Hromadný import (PEM balík)
GET	`/api/v1/certificates/:id/status`	Získat stav odvolání
POST	`/api/v1/certificates/:id/archive`	Archivovat certifikát
POST	`/api/v1/certificates/:id/restore`	Obnovit certifikát z archivu
DELETE	`/api/v1/certificates/:id/permanent`	Trvalé smazání
POST	`/api/v1/certificates/:id/renew`	Obnovit (renew) certifikát
GET	`/api/v1/certificates/:id/renewal-history`	Historie obnovení
GET	`/api/v1/certificates/:id/rotation/config`	Konfigurace rotace
PUT	`/api/v1/certificates/:id/rotation/config`	Aktualizovat konfiguraci rotace
POST	`/api/v1/certificates/:id/rotation/trigger`	Spustit rotaci
GET	`/api/v1/certificates/:id/rotation/history`	Historie rotace
CRUD	`/api/v1/certificates/:id/targets`	Správa cílů rotace
POST	`/api/v1/discovered-certificates/:id/assign`	Změnit vazbu objeveného inventáře na projekt
POST	`/api/v1/discovered-certificates/:id/adopt`	Převzít objevený inventář jako spravovaný certifikát
POST	`/api/v1/discovered-certificates/:id/import-key`	Importovat privátní klíč k převzatému certifikátu
POST	`/api/v1/discovered-certificates/bulk/assign`	Hromadně změnit vazbu na projekt
POST	`/api/v1/discovered-certificates/bulk/adopt`	Hromadně převzít objevený inventář
GET	`/api/v1/ca/:id/crl`	Stáhnout CRL (DER, per-CA)
POST	`/api/v1/ca/:id/crl/regenerate`	Vynutit regeneraci CRL

Přiřazení a převzetí objeveného certifikátu¶

Operace assign a adopt mají odlišný dopad na životní cyklus:

Operace	Způsobilý inventář	Výsledek
`assign`	Objevený inventář včetně položek již propojených se spravovaným certifikátem	Změní pouze vazbu na projekt. Pokud je inventář již spravovaný, jeho stav ve spravovaném životním cyklu zůstane zachován.
`adopt`	Nespravovaný inventář ve stavu `DISCOVERED` nebo `ASSIGNED`	Vytvoří nebo propojí spravovaný certifikát a převede inventář do spravovaného životního cyklu. Cílem musí být certifikátový projekt a prostředí musí existovat v autentizované organizaci a být pro projekt povoleno.

Přiřazení k projektu¶

POST /api/v1/discovered-certificates/550e8400-e29b-41d4-a716-446655440020/assign HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

{
  "project_id": "550e8400-e29b-41d4-a716-446655440001"
}

Přiřazení nevytvoří spravovaný certifikát a neresetuje existující spravovaný stav.

Převzetí do správy¶

POST /api/v1/discovered-certificates/550e8400-e29b-41d4-a716-446655440020/adopt HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

{
  "project_id": "550e8400-e29b-41d4-a716-446655440001",
  "environment": "production",
  "auto_renew_enabled": true
}

Převzetí zaznamená metadata certifikátu a vlastnictví životního cyklu, ale nepřenese do MazeVault úschovu privátního klíče. Nově vytvořený spravovaný certifikát má private_key_storage_mode nastaveno na none, i když discovery hlásí existenci privátního klíče ve zdrojovém umístění.

Úschova privátního klíče

Import privátního klíče je samostatná operace dostupná až po převzetí. Pokud chcete vědomě převést úschovu klíče do MazeVault, použijte POST /api/v1/discovered-certificates/:id/import-key. Samotné převzetí klíč nikdy neimportuje.

Hromadné operace¶

Hromadný výběr musí být homogenní: pro bulk/assign vyberte pouze spravovaný inventář, nebo pro bulk/adopt pouze nespravovaný inventář ve stavu DISCOVERED/ASSIGNED. Webové rozhraní smíšený výběr odmítne a ani přes API se nesmí odeslat jako jedna operace.

Odeslání CSR¶

Backend očekává předem vygenerovaný CSR v PEM formátu — klíčové páry a pole subjektu jsou zakódovány klientem před odesláním.

POST /api/v1/certificates/csr HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

{
  "csr_pem": "-----BEGIN CERTIFICATE REQUEST-----\nMIIC...\n-----END CERTIFICATE REQUEST-----",
  "template_id": "tmpl_web_server",
  "agent_id": "agent_abc123",
  "project_id": "proj_abc123",
  "requested_cn": "api.example.com"
}

Pole požadavku¶

Pole	Typ	Povinné	Popis
`csr_pem`	string	✅	PEM-kódovaný PKCS#10 CSR (vygenerovaný klientem)
`template_id`	string	✅	ID šablony certifikátu (`tmpl_web_server`, `tmpl_client_auth` atd.)
`agent_id`	string	—	ID agenta odesílajícího CSR
`project_id`	string	✅	ID projektu
`requested_cn`	string	—	Požadovaný Common Name (přepisuje CN v CSR, pokud to politika povoluje)

Odpověď `201 Created`¶

{
  "id": "cert_def456",
  "common_name": "api.example.com",
  "status": "pending_approval",
  "serial_number": "01:AB:CD:EF:12:34",
  "ca_id": "ca_root001",
  "project_id": "proj_abc123",
  "requested_at": "2026-02-10T14:30:00Z",
  "requested_by": "usr_abc123"
}

Výpis certifikátů¶

GET /api/v1/certificates?project_id=proj_abc123&status=active&page=1 HTTP/1.1
Authorization: Bearer <token>

Parametry dotazu¶

Parametr	Typ	Popis
`project_id`	string	Filtrovat podle projektu
`status`	string	Filtrovat: `active`, `pending_approval`, `revoked`, `expired`
`ca_id`	string	Filtrovat podle vydávající CA
`common_name`	string	Vyhledávat podle CN (shoda podřetězce)
`expiring_within_days`	integer	Certifikáty s expirací do N dnů
`page`	integer	Číslo stránky
`per_page`	integer	Položek na stránku (max: 100)

Odpověď `200 OK`¶

{
  "data": [
    {
      "id": "cert_def456",
      "common_name": "api.example.com",
      "serial_number": "01:AB:CD:EF:12:34",
      "status": "active",
      "issuer_cn": "MazeVault Internal CA",
      "not_before": "2026-02-10T00:00:00Z",
      "not_after": "2027-02-10T00:00:00Z",
      "key_type": "RSA-2048",
      "san": ["api.example.com", "api-internal.example.com"],
      "project_id": "proj_abc123"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 1
  }
}

Odvolání certifikátu¶

POST /api/v1/certificates/cert_def456/revoke HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

{
  "reason": "keyCompromise",
  "comment": "Private key exposed in security incident"
}

Kódy důvodů odvolání (RFC 5280)¶

Kód	Důvod	Popis
0	`unspecified`	Bez konkrétního důvodu
1	`keyCompromise`	Kompromitace privátního klíče
2	`caCompromise`	Kompromitace privátního klíče CA
3	`affiliationChanged`	Změna příslušnosti subjektu
4	`superseded`	Certifikát nahrazen novým
5	`cessationOfOperation`	Subjekt ukončil provoz
6	`certificateHold`	Dočasné pozastavení (reverzibilní)

Odpověď `200 OK`¶

{
  "id": "cert_def456",
  "status": "revoked",
  "revocation_reason": "keyCompromise",
  "revoked_at": "2026-02-10T15:00:00Z",
  "revoked_by": "usr_abc123"
}

Import certifikátu¶

Jednotlivý import¶

POST /api/v1/certificates/import HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

{
  "certificate_pem": "-----BEGIN CERTIFICATE-----\nMIID...\n-----END CERTIFICATE-----",
  "private_key_pem": "***REMOVED***",
  "chain_pem": "-----BEGIN CERTIFICATE-----\nMIID...\n-----END CERTIFICATE-----",
  "project_id": "proj_abc123"
}

Pole	Typ	Povinné	Popis
`certificate_pem`	string	✅	Certifikát v PEM formátu
`private_key_pem`	string	—	Privátní klíč v PEM formátu
`chain_pem`	string	—	Řetězec CA v PEM formátu
`project_id`	string	✅	Cílový projekt

Hromadný import (PEM balík)¶

POST /api/v1/certificates/import/bulk HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

{
  "pem_bundle": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
  "project_id": "proj_abc123"
}

Export certifikátu¶

GET /api/v1/certificates/cert_def456/export?format=pem HTTP/1.1
Authorization: Bearer <token>

Parametry dotazu¶

Parametr	Hodnoty	Popis
`format`	`pem`, `der`, `pkcs12`	Formát exportu
`include_chain`	`true`, `false`	Zahrnout řetězec CA (výchozí: true)
`include_key`	`true`, `false`	Zahrnout privátní klíč (výchozí: false)
`password`	string	Heslo pro PKCS#12 export (povinné pro pkcs12)

Audit

Exporty certifikátů zahrnující privátní klíč jsou zaznamenány jako auditní události s vysokou závažností.

ACME protokol — endpointy¶

MazeVault poskytuje plnohodnotný ACME server (RFC 8555) pro automatizovanou správu certifikátů. Tyto endpointy využívají ACME klienti jako cert-manager.

Přehled ACME endpointů¶

Metoda	Endpoint	Popis
GET	`/api/acme/directory`	ACME adresář (discovery)
HEAD	`/api/acme/new-nonce`	Získat replay-protection nonce
POST	`/api/acme/new-nonce`	Získat replay-protection nonce
POST	`/api/acme/new-account`	Registrace nového účtu (vyžaduje EAB)
POST	`/api/acme/new-order`	Vytvoření objednávky certifikátu
POST	`/api/acme/order/:id`	Získat stav objednávky
POST	`/api/acme/authz/:id`	Získat detail autorizace
POST	`/api/acme/challenge/:id`	Spustit validaci výzvy
POST	`/api/acme/finalize/:id`	Odeslat CSR k podpisu
POST	`/api/acme/cert/:id`	Stáhnout vydaný certifikát

ACME adresář¶

GET /api/acme/directory HTTP/1.1

Odpověď 200 OK:

{
  "newNonce": "https://vault.example.com/api/acme/new-nonce",
  "newAccount": "https://vault.example.com/api/acme/new-account",
  "newOrder": "https://vault.example.com/api/acme/new-order",
  "revokeCert": "https://vault.example.com/api/acme/revoke-cert",
  "keyChange": "https://vault.example.com/api/acme/key-change",
  "meta": {
    "externalAccountRequired": true,
    "profiles": {
      "web-server": { "description": "Template: Web Server TLS" },
      "client-auth": { "description": "Template: Client Authentication" }
    }
  }
}

Správa EAB přihlašovacích údajů¶

Metoda	Endpoint	Oprávnění	Popis
POST	`/api/v1/organizations/:id/acme-credentials`	`ca:write`	Vytvořit EAB přihlašovací údaje
GET	`/api/v1/organizations/:id/acme-credentials`	`ca:read`	Vypsat EAB přihlašovací údaje
DELETE	`/api/v1/organizations/:id/acme-credentials/:credId`	`ca:write`	Odvolat EAB přihlašovací údaje

Vytvoření EAB přihlašovacích údajů¶

POST /api/v1/organizations/{org_id}/acme-credentials HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

{
  "project_id": "proj_abc123",
  "default_template_id": "tmpl_def456",
  "cluster_label": "prod-aks-westeurope"
}

Odpověď 201 Created:

{
  "id": "cred_xyz789",
  "eab_key_id": "***REMOVED***",
  "eab_hmac_key": "***REMOVED***",
  "cluster_label": "prod-aks-westeurope",
  "created_at": "2026-03-14T10:00:00Z"
}

Jednorázový HMAC klíč

Hodnota eab_hmac_key je vrácena pouze při vytvoření. Uložte ji bezpečně — později ji nelze získat.

Podrobný návod na nastavení ACME s cert-managerem a příklady Kubernetes YAML najdete v Návodu pro automatizaci certifikátů pomocí ACME.

Distribuce CRL¶

CRL endpointy jsou per-CA. Každá CA má svůj vlastní distribuční bod CRL.

Stažení CRL¶

GET /api/v1/ca/ca_root001/crl HTTP/1.1
Accept: application/pkix-crl

Vrátí CRL ve formátu DER pro zadanou CA.

Vynucení regenerace CRL¶

POST /api/v1/ca/ca_root001/crl/regenerate HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

{
  "type": "full"
}

Pole	Hodnoty	Popis
`type`	`full`, `delta`	Úplný CRL nebo delta CRL

SCEP endpoint¶

GET /api/v1/scep/:ca_id HTTP/1.1

SCEP operace odpovídají RFC 8894. Podporuje GetCACaps, GetCACert, PKIOperation.

Požadovaná oprávnění¶

Operace	Požadované oprávnění
Odeslat CSR	`certificate:request`
Zobrazit certifikáty	`certificate:read`
Schválit/zamítnout CSR	`certificate:approve`
Odvolat certifikát	`certificate:revoke`
Importovat certifikát	`certificate:import`
Exportovat certifikát	`certificate:read`
Archivovat / Obnovit	`certificate:archive`
Trvalé smazání	`certificate:permanent_delete`
Spravovat konfiguraci rotace	`rotation:write`
Spustit rotaci	`rotation:execute`
Spustit obnovení	`certificate:write`
Spravovat CRL	`ca:admin`

Archiv certifikátů a životní cyklus¶

Archivovat certifikát¶

POST /api/v1/certificates/cert_def456/archive HTTP/1.1
Authorization: Bearer <token>

Přesune certifikát do archivu.

Obnovit certifikát z archivu¶

POST /api/v1/certificates/cert_def456/restore HTTP/1.1
Authorization: Bearer <token>

Trvalé smazání¶

DELETE /api/v1/certificates/cert_def456/permanent HTTP/1.1
Authorization: Bearer <token>

Nevratné

Trvalé smazání odstraní certifikát a veškerá přidružená data.

Rotace certifikátů¶

Automatizace rotace certifikátů do externích cílů (správci tajemství, load balancery, cloudové služby).

Získat konfiguraci rotace¶

GET /api/v1/certificates/cert_def456/rotation/config HTTP/1.1
Authorization: Bearer <token>

Aktualizovat konfiguraci rotace¶

PUT /api/v1/certificates/cert_def456/rotation/config HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

Spustit rotaci¶

POST /api/v1/certificates/cert_def456/rotation/trigger HTTP/1.1
Authorization: Bearer <token>

Historie rotace¶

GET /api/v1/certificates/cert_def456/rotation/history HTTP/1.1
Authorization: Bearer <token>

Správa cílů rotace¶

Metoda	Endpoint	Popis
POST	`/api/v1/certificates/:id/targets`	Vytvořit cíl rotace
GET	`/api/v1/certificates/:id/targets`	Vypsat cíle rotace
GET	`/api/v1/certificates/:id/targets/:targetId`	Detail cíle
PUT	`/api/v1/certificates/:id/targets/:targetId`	Aktualizovat cíl
DELETE	`/api/v1/certificates/:id/targets/:targetId`	Smazat cíl
POST	`/api/v1/certificates/:id/targets/:targetId/sync`	Ruční synchronizace cíle

Obnovení certifikátu (Renewal)¶

Spustit obnovení¶

POST /api/v1/certificates/cert_def456/renew HTTP/1.1
Authorization: Bearer <token>

Historie obnovení¶

GET /api/v1/certificates/cert_def456/renewal-history HTTP/1.1
Authorization: Bearer <token>

Fronta obnovení¶

Metoda	Endpoint	Popis
GET	`/api/v1/renewal-queue`	Seznam certifikátů čekajících na obnovení
POST	`/api/v1/renewal-queue/:id/approve`	Schválit obnovení
POST	`/api/v1/renewal-queue/:id/cancel`	Zrušit obnovení

Náhled importu¶

Náhled certifikátů před importem:

POST /api/v1/certificates/import/preview HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

Vrátí parsované detaily certifikátu bez importu.

Import souboru¶

POST /api/v1/certificates/import/file HTTP/1.1
Authorization: Bearer <token>
Content-Type: multipart/form-data

Přijímá soubory certifikátů (PEM, DER, PFX/PKCS#12) přes multipart upload.

Související¶

Začínáme — Autentizace a základy API
Průvodce správou certifikátů — Práce s certifikáty přes UI
Konfigurace TLS — Nastavení nasazení TLS

API pro certifikáty¶

Přehled endpointů¶

Přiřazení a převzetí objeveného certifikátu¶

Přiřazení k projektu¶

Převzetí do správy¶

Hromadné operace¶

Odeslání CSR¶

Pole požadavku¶

Odpověď 201 Created¶

Výpis certifikátů¶

Parametry dotazu¶

Odpověď 200 OK¶

Odvolání certifikátu¶

Kódy důvodů odvolání (RFC 5280)¶

Odpověď 200 OK¶

Import certifikátu¶

Jednotlivý import¶

Hromadný import (PEM balík)¶

Export certifikátu¶

Parametry dotazu¶

ACME protokol — endpointy¶

Přehled ACME endpointů¶

ACME adresář¶

Správa EAB přihlašovacích údajů¶

Vytvoření EAB přihlašovacích údajů¶

Distribuce CRL¶

Stažení CRL¶

Vynucení regenerace CRL¶

SCEP endpoint¶

Požadovaná oprávnění¶

Archiv certifikátů a životní cyklus¶

Archivovat certifikát¶

Obnovit certifikát z archivu¶

Trvalé smazání¶

Rotace certifikátů¶

Získat konfiguraci rotace¶

Aktualizovat konfiguraci rotace¶

Spustit rotaci¶

Historie rotace¶

Správa cílů rotace¶

Obnovení certifikátu (Renewal)¶

Spustit obnovení¶

Historie obnovení¶

Fronta obnovení¶

Náhled importu¶

Import souboru¶

Související¶

Odpověď `201 Created`¶

Odpověď `200 OK`¶

Odpověď `200 OK`¶