---
title: "Akceptacja czynności agentów AI — API v1 i MCP | Dokumentacja Nodea"
description: "Czynności kosztowe i destrukcyjne z API v1 i MCP wymagają zatwierdzenia przez człowieka: odpowiedź 202 approval_required, odpytywanie stanu, stany żądania, kto zatwierdza i dziennik zdarzeń."
url: "https://nodea.pl/pl/dokumentacja-api/approvals"
lang: "pl"
updated: "2026-11-18"
---

# Akceptacja czynności agentów AI — API v1 i MCP | Dokumentacja Nodea

> Agent AI nie wykonuje czynności kosztowych ani destrukcyjnych sam: dostaje żądanie akceptacji, człowiek zatwierdza je w panelu, a agent odpytuje stan. Lista czynności, format odpowiedzi, endpointy i narzędzia MCP.

Agent AI — każdy token REST API v1 i każde połączenie MCP, także przez OAuth z klientem takim jak Claude, także tokeny już istniejące i tokeny w CI — **nie wykonuje samodzielnie czynności kosztowych ani destrukcyjnych**. Zamiast tego tworzy **żądanie akceptacji**. Czynność wykonuje się dopiero wtedy, gdy człowiek zatwierdzi ją w panelu (AI → Czynności do zatwierdzenia). Nie ma wyjątków dla wybranych tokenów i nie ma endpointu ani narzędzia, które zatwierdza za człowieka.

**Zmiana niekompatybilna (wydanie z 13.11.2026):** endpointy i narzędzia z tabeli niżej odpowiadają teraz `202` z `code: approval_required` zamiast wykonać czynność. Kod `202` mieści się w zakresie 2xx — skrypt, który sprawdza tylko, czy odpowiedź jest „udana”, uzna czynność za wykonaną. Sprawdzaj pole `code` i odpytuj `status_url`.

## Co wymaga akceptacji

- **Kosztowe** — zamówienie instancji, zmiana planu usługi i każda inna czynność, która generuje opłatę.
- **Destrukcyjne** — usunięcie serwera albo hostingu, zatrzymanie maszyny wirtualnej, przywrócenie kopii hostingu, usunięcie skrzynki pocztowej, usunięcie lub nadpisanie rekordu DNS, zmiana serwerów nazw domeny, kod transferu domeny, zmiana zapory z polityką DROP, usuwająca reguły, dodająca regułę drop/reject albo zmieniająca zbiór adresów, wyłączenie zapory, przywrócenie reguł zapory, zatwierdzenie migracji zapory, usunięcie klucza SSH, odłączenie urządzenia sejfu, cofnięcie udostępnienia, wykonanie i ponowienie migracji.
- **Bez akceptacji** — odczyty i bezpieczne zmiany: start i restart maszyny, migawki, test SSH, notatka, instalacja komponentów, zapis szkicu zapory, odświeżenie zapory, dodanie klucza SSH, nowe rekordy DNS, zmiana TTL, priorytetu i komentarza rekordu, prywatność WHOIS, poczta i kopie hostingu (bez przywracania), zgłoszenia, profil, cały monitoring i alerty.

Wyjątek dla klientów ACME DNS-01: usunięcie rekordu TXT `_acme-challenge` nie wymaga akceptacji (to sprzątanie po wydaniu certyfikatu). Przy zmianie zapory `dry_run: true` i przy zmianie planu `dry_run: true` działają od razu, bo niczego nie zmieniają.

| Metoda | Endpoint | Narzędzie MCP | Typ | Klasa | Kto zatwierdza |
| --- | --- | --- | --- | --- | --- |
| POST | /api/v1/compute/orders | `compute-order-draft` | `compute.order` | kosztowa | właściciel albo członek z `orders` |
| POST | /api/v1/compute/order-drafts | `compute-order-draft` | `compute.order` | kosztowa | właściciel albo członek z `orders` |
| POST | /api/v1/services/{service}/upgrade | `service-upgrade` | `service.upgrade` | kosztowa | właściciel albo członek z `products` + `manageproducts` + `orders` |
| DELETE | /api/v1/servers/{server} | `server-delete` | `server.destroy` | destrukcyjna | właściciel konta |
| POST | /api/v1/servers/{server}/vm/stop | `server-vm-stop` | `server.vm.stop` | destrukcyjna | właściciel albo członek z `manageproducts` |
| POST | /api/v1/servers/{server}/firewall/apply | `server-firewall-apply` | `server.firewall.apply` | destrukcyjna | właściciel albo członek z `manageproducts` |
| POST | /api/v1/servers/{server}/firewall/disable | `server-firewall-disable` | `server.firewall.disable` | destrukcyjna | właściciel albo członek z `manageproducts` |
| POST | /api/v1/servers/{server}/firewall/drift/restore | — | `server.firewall.drift_restore` | destrukcyjna | właściciel albo członek z `manageproducts` |
| POST | /api/v1/servers/{server}/firewall/migration/commit | `server-firewall-migration` | `server.firewall.migration_commit` | destrukcyjna | właściciel albo członek z `manageproducts` |
| DELETE | /api/v1/dns/zones/{zone}/records/{record} | `dns-record-delete` | `dns.record.delete` | destrukcyjna | właściciel albo członek z `managedomains` |
| DELETE | /api/v1/dns/zones/{zone}/records | — | `dns.record.delete` | destrukcyjna | właściciel albo członek z `managedomains` |
| PATCH | /api/v1/dns/zones/{zone}/records/{record} | `dns-record-update` | `dns.record.update` | destrukcyjna | właściciel albo członek z `managedomains` |
| PATCH | /api/v1/domains/{domain} | `domain-set-nameservers` | `domain.nameservers` | destrukcyjna | właściciel albo członek z `domains` + `managedomains` |
| POST | /api/v1/domains/{domain}/epp | `domain-request-epp` | `domain.epp` | destrukcyjna | właściciel albo członek z `domains` + `managedomains` |
| DELETE | /api/v1/hosting/{account} | `hosting-terminate` | `hosting.terminate` | destrukcyjna | właściciel konta |
| POST | /api/v1/hosting/{account}/backups/{backup}/restore | `hosting-backup-restore` | `hosting.backup.restore` | destrukcyjna | właściciel konta |
| DELETE | /api/v1/hosting/{account}/emails/{email} | `hosting-email-delete` | `hosting.email.delete` | destrukcyjna | właściciel albo członek z `products` + `manageproducts` |
| DELETE | /api/v1/branding | `branding-delete` | `branding.delete` | destrukcyjna | właściciel albo członek z `products` + `manageproducts` (serwer bez konta — użytkownik tokenu) |
| DELETE | /api/v1/servers/{server}/branding | `branding-delete` | `branding.delete` | destrukcyjna | właściciel albo członek z `products` + `manageproducts` (serwer bez konta — użytkownik tokenu) |
| DELETE | /api/v1/servers/{server}/branding/domains/{host} | `branding-delete` | `branding.delete` | destrukcyjna | właściciel albo członek z `products` + `manageproducts` (serwer bez konta — użytkownik tokenu) |
| DELETE | /api/v1/ssh-keys/{sshKey} | `ssh-key-delete` | `ssh_key.delete` | destrukcyjna | użytkownik tokenu (zasób osobisty) |
| DELETE | /api/v1/vault-devices/{device} | `vault-device-revoke` | `vault_device.revoke` | destrukcyjna | użytkownik tokenu (zasób osobisty) |
| DELETE | /api/v1/shares/{share} | `share-revoke` | `share.revoke` | destrukcyjna | użytkownik tokenu (zasób osobisty) |
| POST | /api/v1/migrations/{run}/execute | `migration-execute` | `migration.execute` | destrukcyjna | użytkownik tokenu (zasób osobisty) |
| POST | /api/v1/migrations/{run}/retry-failed | `migration-retry-failed` | `migration.retry_failed` | destrukcyjna | użytkownik tokenu (zasób osobisty) |

## Odpowiedź z żądaniem akceptacji

Autoryzacja, uprawnienia konta i walidacja działają jak zawsze — błędy (`401`, `403`, `404`, `409`, `422`, `423`) wracają od razu i żadne żądanie nie powstaje. Gdy czynność jest dozwolona, odpowiedź to `202 Accepted` z nagłówkiem `Retry-After: 30`:

```json
{
  "message": "Ta czynność wymaga zatwierdzenia przez człowieka. …",
  "code": "approval_required",
  "data": {
    "approval_request": {
      "id": "01jcz8m3w7v1t2n9q4r5s6t7u8",
      "status": "pending",
      "type": "server.destroy",
      "classification": "destructive",
      "subject": { "type": "App\\Models\\Server", "id": "42", "label": "web-01" },
      "effect": "Usunięcie serwera web-01. …",
      "quote": null,
      "created_at": "2026-11-13T12:00:00+01:00",
      "expires_at": "2026-11-14T12:00:00+01:00",
      "decided_at": null,
      "decided_by_human": false,
      "executed_at": null,
      "result": null,
      "approve_url": "https://app.nodea.io/app/ai/approvals/01jcz8m3w7v1t2n9q4r5s6t7u8",
      "status_url": "https://app.nodea.io/api/v1/approval-requests/01jcz8m3w7v1t2n9q4r5s6t7u8",
      "poll_after_seconds": 30
    }
  }
}
```

- `approve_url` — strona żądania w panelu. Przekaż ją człowiekowi.
- `quote` — wycena czynności kosztowej (netto); przy zatwierdzeniu człowiek widzi tę samą kwotę. Gdy cena zmieni się przed wykonaniem, wykonanie kończy się błędem `quote_changed` i trzeba poprosić o nowe zatwierdzenie.
- `expires_at` — żądanie jest ważne **24 godziny**, potem przechodzi w `expired`.
- Ta sama czynność z tymi samymi parametrami, powtórzona przez tego samego użytkownika w czasie oczekiwania, zwraca istniejące żądanie z kodem `200`. Nagłówek `Idempotency-Key` (do 64 znaków `A-Za-z0-9._:-`) zwraca zawsze to samo żądanie dla tego samego klucza.

W MCP narzędzie zwraca zwykły wynik (nie błąd) z `code: approval_required`, `message` z instrukcją dla agenta i `approval_request` o tym samym kształcie.

## Stany żądania

- `pending` — czeka na decyzję człowieka.
- `approved`, `executing` — zatwierdzone, platforma wykonuje czynność w tle.
- `succeeded` — wykonane; `result.ids` zawiera identyfikatory z odpowiedzi (np. `task_id`, `revision`, `operation_id`), a `result.order_id` — zamówienie.
- `failed` — wykonanie nie powiodło się; `result.error_code` podaje powód (np. kod błędu endpointu, `approval_mismatch` gdy zasób zmienił się od zatwierdzenia, `quote_changed`, `token_revoked`, `approver_lost_permission`).
- `rejected`, `expired`, `cancelled` — nic nie zostało wykonane.

Przy wykonaniu platforma powtarza wywołanie agenta tym samym tokenem i w tym samym koncie: zakres tokenu, uprawnienia konta, blokady i stan zasobu są sprawdzane ponownie. Odwołanie tokenu przed decyzją anuluje żądanie. Agent nie poznaje danych osoby, która zdecydowała — widzi tylko `decided_by_human: true`.

## Endpointy żądań akceptacji

Działają z każdym zakresem tokenu. Token osobisty widzi wyłącznie żądania, które sam utworzył; klient OAuth (np. połączenie MCP z Claude) — żądania swojego połączenia, także po odświeżeniu tokenu dostępu. Inne zwracają `404`.

| Metoda | Endpoint | Scope | Opis |
| --- | --- | --- | --- |
| GET | /api/v1/approval-requests | dowolny | Lista żądań tokenu, najnowsze pierwsze. Parametry: `status` (jeden ze stanów), `per_page` (1–50, domyślnie 20). Odpowiedź: `data[]` i `meta` (`current_page`, `last_page`, `per_page`, `total`). |
| GET | /api/v1/approval-requests/{id} | dowolny | Stan jednego żądania (ten sam kształt co w odpowiedzi `202`). Odpytuj co `poll_after_seconds` (nagłówek `Retry-After`). |
| POST | /api/v1/approval-requests/{id}/cancel | dowolny | Wycofanie własnego żądania w stanie `pending`. Żądanie już rozstrzygnięte — `409` z `code: approval_not_pending`. |

Narzędzia MCP (zakres transportowy `mcp:use`, bez innych zakresów):

| Narzędzie | Opis |
| --- | --- |
| `approval-requests-list` | Żądania tego połączenia (opcjonalnie `status`), najwyżej 50. |
| `approval-request-get` | Stan jednego żądania (`id`). |
| `approval-request-cancel` | Wycofanie żądania w stanie `pending` (`id`); inaczej błąd `(code: approval_not_pending)`. |

## Kto zatwierdza

Zatwierdza człowiek w panelu, w sesji przeglądarki: właściciel konta albo członek z uprawnieniem odpowiednim do czynności (tabela wyżej). Usunięcie serwera z maszyną wirtualną, usunięcie hostingu i przywrócenie kopii hostingu zatwierdza tylko właściciel. Klucze SSH, urządzenia sejfu, udostępnienia i migracje należą do użytkownika — zatwierdza je użytkownik tokenu. Czynność destrukcyjną zatwierdza się, wpisując nazwę zasobu. Administrator Nodea widzi żądania, ale ich nie zatwierdza. Powiadomienia: pozycja w sekcji „Czekają”, licznik w menu, e-mail i powiadomienie w przeglądarce.

## Dziennik zdarzeń akceptacji

Każde żądanie i każda decyzja trafia do dziennika, którego nie można zmienić ani usunąć i który nie jest automatycznie czyszczony: utworzenie (token, klient MCP, użytkownik, adres IP, klient HTTP, parametry, wycena), zatwierdzenie i odrzucenie (kto — imię i nazwisko, e-mail i rola w chwili decyzji, adres IP, potwierdzona nazwa zasobu, powód), wygaśnięcie, anulowanie oraz wynik wykonania. Wpisy są powiązane skrótem SHA-256. Dziennik z filtrami i eksportem CSV jest w panelu (AI → Czynności do zatwierdzenia → Dziennik).

## Przykład — agent usuwa serwer

```bash
# 1. Agent prosi o usunięcie
curl -s -X DELETE https://app.nodea.io/api/v1/servers/42 \
  -H "Authorization: Bearer $NODEA_TOKEN" -H "Accept: application/json"
# HTTP 202 — code: approval_required, data.approval_request.id = 01jcz8…

# 2. Człowiek zatwierdza w panelu (approve_url), wpisując „web-01”

# 3. Agent odpytuje stan
curl -s https://app.nodea.io/api/v1/approval-requests/01jcz8m3w7v1t2n9q4r5s6t7u8 \
  -H "Authorization: Bearer $NODEA_TOKEN" -H "Accept: application/json"
# { "data": { "status": "succeeded", "result": { "success": true, … }, … } }
```

## Powiązane

- [API Nodea v1 — wprowadzenie: base URL, tokeny, scope'y, limity | Nodea](https://nodea.pl/pl/dokumentacja-api/overview)
- [Serwer MCP Nodea — endpoint, uwierzytelnianie, discovery OAuth, narzędzia | Nodea](https://nodea.pl/pl/dokumentacja-api/mcp)
- [Wdrożenia z agentów AI — Claude Code, Codex, OpenCode i CI | Nodea](https://nodea.pl/pl/dokumentacja-api/ai-coding-agents)
- [Serwery — API v1 i MCP | Dokumentacja Nodea](https://nodea.pl/pl/dokumentacja-api/servers)

---

Wersje językowe: [en](https://nodea.io/en/api-docs/approvals.md)  
Spis treści witryny: [llms.txt](https://nodea.pl/pl/llms.txt)
