API pro agenty¶

Registrace agentů, heartbeat, discovery a správa

Verze dokumentu: 1.1.0
Poslední aktualizace: 2026-04-04

Přehled¶

Agenti MazeVault jsou lehké procesy nasazené na uzlech infrastruktury, které zajišťují:

Automatické vkládání tajemství do aplikací
Objevování certifikátů napříč spravovanou infrastrukturou
Synchronizaci tajemství a certifikátů v reálném čase
Bezpečný proxy pro přístup lokálních aplikací k tajemstvím

Přehled endpointů¶

Metoda	Endpoint	Autentizace	Popis
POST	`/api/v1/agents/register`	Bootstrap token	Registrovat nového agenta
POST	`/api/v1/agents/bootstrap`	JWT + `agent:admin`	Vygenerovat bootstrap token
GET	`/api/v1/agents`	JWT + `agent:admin`	Zobrazit agenty
GET	`/api/v1/agents/:id/discovery`	JWT + `agent:admin`	Získat výsledky discovery agenta
GET	`/api/v1/agents/update/latest`	Agent Cert	Zkontrolovat aktualizace agenta
POST	`/api/v1/agents/me/refresh-token`	mTLS	Obnovit token agenta
POST	`/api/v1/agents/me/health`	JWT	Nahlásit stav agenta
GET	`/api/v1/agents/me/certificates`	JWT	Získat přiřazené certifikáty
GET	`/api/v1/agents/me/connect`	JWT	WebSocket připojení agenta
POST	`/api/v1/agents/me/discovery/certificates`	JWT	Nahlásit objevené certifikáty
POST	`/api/v1/agents/me/password-requests`	JWT	Vytvořit žádost o heslo
GET	`/api/v1/agents/me/password-requests`	JWT	Získat čekající odpovědi na hesla
POST	`/api/v1/agents/me/ssh-discovery`	JWT	Nahlásit objevené SSH klíče

Registrace agenta¶

Krok 1: Vygenerování bootstrap tokenu¶

Vytvořte bootstrap token ve webovém rozhraní MazeVault:

Nastavení → Agenti → Vygenerovat bootstrap token

Token je platný po konfigurovatelnou dobu (výchozí: 24 hodin) a může být použit pro stanovený počet registrací.

Krok 2: Registrace agenta¶

POST /api/v1/agents/register HTTP/1.1
Content-Type: application/json

{
  "token": "***REMOVED***",
  "name": "app-server-01",
  "hostname": "app-server-01.example.com",
  "os_type": "linux",
  "metadata": {
    "environment": "production",
    "datacenter": "eu-west-1",
    "role": "application-server"
  }
}

Pole požadavku¶

Pole	Typ	Povinné	Popis
`token`	string	✅	Bootstrap token
`name`	string	✅	Zobrazovaný název agenta
`hostname`	string	—	FQDN hostitele
`os_type`	string	—	Typ operačního systému (např. `linux`, `windows`)
`metadata`	object	—	Metadata klíč–hodnota (nahrazuje labels)

Odpověď `201 Created`¶

{
  "id": "agt_xyz789",
  "token": "eyJ...",
  "mtls_template_id": "tmpl_agent_mtls"
}

Pole	Popis
`id`	ID agenta pro následné požadavky
`token`	JWT token pro autentizované API volání
`mtls_template_id`	ID šablony certifikátu pro mTLS registraci

Stav agenta (Health)¶

Agenti pravidelně hlásí svůj stav:

POST /api/v1/agents/me/health HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

{
  "status": "healthy",
  "uptime_seconds": 86400,
  "metrics": {
    "cpu_percent": 15.2,
    "memory_percent": 42.8,
    "disk_percent": 67.1
  },
  "managed_secrets": 12,
  "managed_certificates": 5,
  "last_sync": "2026-02-10T16:55:00Z"
}

Odpověď `200 OK`¶

{
  "acknowledged": true,
  "server_time": "2026-02-10T17:00:00Z",
  "commands": []
}

Pole commands může obsahovat čekající instrukce pro agenta (např. vynucení synchronizace, obnovení certifikátu).

Objevování certifikátů¶

Agenti mohou skenovat svou lokální infrastrukturu a hlásit objevené certifikáty:

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

{
  "certificates": [
    {
      "subject": "CN=legacy-app.internal,O=Example Corp",
      "serial_number": "AB:CD:EF:01:23",
      "issuer": "CN=Internal CA",
      "not_before": "2025-06-15T00:00:00Z",
      "not_after": "2026-06-15T00:00:00Z",
      "location": "/etc/ssl/certs/legacy-app.pem",
      "fingerprint": "SHA256:abc123...",
      "dns_names": ["legacy-app.internal"],
      "ip_addresses": ["10.0.2.50"],
      "source": "filesystem",
      "is_managed": false
    }
  ]
}

Odpověď `200 OK`¶

{
  "accepted": 1,
  "duplicates": 0,
  "errors": 0
}

Objevené certifikáty se zobrazí ve webovém rozhraní MazeVault v sekci Certifikáty → Objevené k přezkoumání a volitelnému importu.

Výpis agentů¶

GET /api/v1/agents?status=online&page=1 HTTP/1.1
Authorization: Bearer <token>

Pouze pro administrátory

Tento endpoint vyžaduje oprávnění agent:admin.

Parametry dotazu¶

Parametr	Typ	Popis
`status`	string	Filtrovat: `online`, `offline`, `degraded`
`label`	string	Filtrovat podle štítku (klíč=hodnota)
`search`	string	Vyhledávat podle hostname
`page`	integer	Číslo stránky
`per_page`	integer	Položek na stránku

Odpověď `200 OK`¶

{
  "data": [
    {
      "id": "agt_xyz789",
      "hostname": "app-server-01.example.com",
      "status": "online",
      "platform": "linux/amd64",
      "agent_version": "1.8.0",
      "labels": {
        "environment": "production",
        "datacenter": "eu-west-1"
      },
      "last_heartbeat": "2026-02-10T17:00:00Z",
      "managed_secrets": 12,
      "managed_certificates": 5,
      "registered_at": "2026-01-15T10:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 1
  }
}

Stavy agenta¶

Stav	Popis	Podmínka
`online`	Agent je zdravý a hlásí se	Poslední heartbeat < 2× interval
`degraded`	Agent hlásí problémy	Heartbeat přijat, ale metriky ukazují problémy
`offline`	Agent neodpovídá	Poslední heartbeat > 3× interval

Životní cyklus agenta¶

Operace životního cyklu registrovaného agenta v řídicí rovině. Všechny vyžadují oprávnění agent:admin. Odregistrace nebo revokace agenta zneplatní jeho mTLS identitu a recovery tokeny a zablokuje veškeré budoucí runtime použití; historie zůstává zachována. Tyto operace nemažou vygenerovaný instalační záznam (viz DELETE /api/v1/deployments/{id}).

Získat dopad životního cyklu¶

GET /api/v1/agents/{id}/lifecycle-impact HTTP/1.1
Authorization: Bearer <jwt>

Vrací orientační přehled závislostí (spravované certifikáty, vazby na projekty, rotační cíle, SSH klíče, čekající keytab nasazení, discovery/config/token reference) plus blockers a warnings. Počty jsou best-effort; payloady gateway tasků nejsou plně prohledány.

Odregistrovat agenta¶

POST /api/v1/agents/{id}/unregister HTTP/1.1
Authorization: Bearer <jwt>
Content-Type: application/json

{ "reason": "vyřazení hosta", "reason_category": "decommission", "force": false }

reason_category compromised, lost_credential nebo stolen_host povýší vyřazení na bezpečnostní revokaci. Bez force vrací nevyřešené blockery (spravované certifikáty, čekající keytab nasazení) 409 Conflict. Odpověď 200 OK vrací výsledek životního cyklu.

Přeregistrovat agenta (vydat náhradní token)¶

POST /api/v1/agents/{id}/reregister HTTP/1.1
Authorization: Bearer <jwt>

{ "reason": "kompromitovaný mTLS certifikát" }

Vyřadí starou identitu (pokud je stále aktivní) a vrátí jednorázový náhradní bootstrap token (platnost 24 h) pro opětovné zaregistrování hosta.

Vzdáleně odinstalovat agenta¶

POST /api/v1/agents/{id}/uninstall HTTP/1.1
Authorization: Bearer <jwt>

{ "reason": "vyřazení hosta" }

Požádá připojeného agenta, aby se sám odinstaloval. Vyžaduje živé připojení a podporovanou platformu (Linux systemd balíčkové instalace nebo Windows MSI service instalace). Vrací 202 Accepted při přijetí agentem, 409 Conflict pokud agent není připojen/aktivní, nebo 422 Unprocessable Entity pokud platforma/rozložení není podporováno (použijte odregistraci + ruční odstranění).

202 Accepted znamená, že žádost byla přijata, nikoli že host byl odstraněn. Odpojený runner provede odinstalaci a nahlásí terminální výsledek přes health kanál (POST /api/v1/agents/me/health s blokem uninstall). Při nahlášeném úspěchu je agent automaticky vyřazen; při selhání zůstává aktivní s uninstall_status = failed pro opakování. Pokud report nedorazí, agent je zobrazen jako čekající na potvrzení.

Požadovaná oprávnění¶

Operace	Požadované oprávnění
Registrovat agenta	Bootstrap token (bez uživatelské autentizace)
Zobrazit agenty	`agent:admin`
Vygenerovat bootstrap token	`agent:admin`
Získat výsledky discovery	`agent:admin`
Dopad / odregistrace / přeregistrace / odinstalace	`agent:admin`
Health / Discovery / Password-requests	Agent JWT (self-service)
Obnovit token	mTLS klientský certifikát

Žádosti o hesla agenta¶

Agenti mohou žádat o rotaci hesel jménem spravovaných služeb:

Vytvořit žádost o heslo¶

POST /api/v1/agents/me/password-requests HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

Získat čekající odpovědi¶

GET /api/v1/agents/me/password-requests HTTP/1.1
Authorization: Bearer <token>

Administrace žádostí o hesla¶

Metoda	Endpoint	Oprávnění	Popis
GET	`/api/v1/admin/password-requests`	`agent:admin`	Seznam všech žádostí
POST	`/api/v1/admin/password-requests/:id/approve`	`agent:admin`	Schválit žádost
POST	`/api/v1/admin/password-requests/:id/reject`	`agent:admin`	Zamítnout žádost

Objevování SSH klíčů¶

Agenti mohou hlásit objevené SSH klíče ze spravovaných hostitelů:

POST /api/v1/agents/me/ssh-discovery HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

Správa SSH klíčů je dostupná na /api/v1/ssh/discovery (vyžaduje oprávnění ssh:discover).

Kontrola aktualizací agenta¶

GET /api/v1/agents/update/latest HTTP/1.1

Vrátí nejnovější dostupnou verzi agenta pro automatické aktualizace.

Související¶

Začínáme — Autentizace API
API pro tajemství — Správa tajemství
Průvodce rychlým startem — Počáteční nastavení

API pro agenty¶

Přehled¶

Přehled endpointů¶

Registrace agenta¶

Krok 1: Vygenerování bootstrap tokenu¶

Krok 2: Registrace agenta¶

Pole požadavku¶

Odpověď 201 Created¶

Stav agenta (Health)¶

Odpověď 200 OK¶

Objevování certifikátů¶

Odpověď 200 OK¶

Výpis agentů¶

Parametry dotazu¶

Odpověď 200 OK¶

Stavy agenta¶

Životní cyklus agenta¶

Získat dopad životního cyklu¶

Odregistrovat agenta¶

Přeregistrovat agenta (vydat náhradní token)¶

Vzdáleně odinstalovat agenta¶

Požadovaná oprávnění¶

Žádosti o hesla agenta¶

Vytvořit žádost o heslo¶

Získat čekající odpovědi¶

Administrace žádostí o hesla¶

Objevování SSH klíčů¶

Kontrola aktualizací agenta¶

Související¶

Odpověď `201 Created`¶

Odpověď `200 OK`¶

Odpověď `200 OK`¶

Odpověď `200 OK`¶