--- title: "Hosting (DirectAdmin) — API v1 i MCP | Dokumentacja Nodea" description: "Pełny reference modułu Hosting DirectAdmin: endpointy REST API v1 (konta, skrzynki e-mail, kopie zapasowe + restore, SSL, terminacja), zakresy account:*, narzędzia MCP oraz przykłady curl i JSON-RPC." url: "https://nodea.pl/pl/dokumentacja-api/hosting" lang: "pl" updated: "2026-07-16" --- # Hosting (DirectAdmin) — API v1 i MCP | Dokumentacja Nodea > Reference modułu Hosting (DirectAdmin) — endpointy API v1 (konta, skrzynki e-mail CRUD, kopie zapasowe + restore, wydanie SSL, terminacja konta), zakresy account:read/write/delete, narzędzia MCP i przykłady. Hasła skrzynek są tylko do zapisu, poświadczenia DA nigdy nie wracają. Moduł **Hosting** obejmuje konta hostingowe DirectAdmin konta klienta: listowanie i szczegóły konta, zarządzanie skrzynkami e-mail, kopie zapasowe wraz z przywracaniem, wydanie certyfikatu Let's Encrypt oraz terminację konta. Dokument opisuje warstwę REST API v1 (/api/v1) oraz narzędzia MCP z tego modułu. ## Uwierzytelnianie i zakresy (scopes) API v1 uwierzytelnia się osobistym tokenem Passport przez nagłówek Authorization: Bearer \. Trasy tego modułu są chronione zakresem konta odpowiadającym poziomowi operacji: - account:read — listowanie i podgląd (konto, skrzynki, kopie). - account:write — tworzenie/edycja/usuwanie skrzynek, tworzenie kopii, wydanie SSL. - account:delete — przywracanie kopii (nadpisuje stan) oraz terminacja konta. Cały moduł jest dodatkowo bramkowany flagą Pennant features:hosting-suite — wyłączenie ukrywa go w web UI i w API. Limit zapytań: throttle:api-v1 = 240/min na użytkownika tokenu. W MCP każde narzędzie wymaga dodatkowo zakresu transportowego mcp:use oraz flagi hosting-suite. ## Konto klienta, własność i widoczność Konta hostingowe należą do **konta klienta** (patrz [Konta klientów](https://nodea.pl/pl/dokumentacja-api/accounts)). Żądanie działa w bieżącym koncie (przypięcie tokenu → nagłówek X-Account-Id → konto domyślne), a obok scope'a tokenu wymagane jest uprawnienie konta: EndpointUprawnienie kontaGET /hosting, GET /hosting/{account}, GET …/emails, GET …/backupsproducts Skrzynki (POST/PATCH/DELETE …/emails), POST …/backups, POST …/backups/{backup}/restore, POST …/sslproducts + manageproducts DELETE /hosting/{account} (terminacja)tylko **właściciel** konta klienta (account\_owner\_required) Lista zwraca wyłącznie konta hostingowe **bieżącego konta**, a HostingAccountResource niesie pole account\_id. Skrzynki i kopie są sprawdzane dwukrotnie: konto hostingowe musi należeć do bieżącego konta klienta, a skrzynka/kopia — do tego konta hostingowego. Każde niedopasowanie (także zasób innego Twojego konta) zwraca 404 (a nie 403), więc API nie potwierdza istnienia cudzego zasobu. W MCP odpowiada temu jeden komunikat „nie znaleziono lub brak dostępu”. **Kolejność sprawdzeń przy terminacji** (DELETE /hosting/{account}): 404 (konto spoza bieżącego konta) → 423 managed\_by\_whmcs (konto zarządzane w panelu rozliczeń WHMCS — zawsze, niezależnie od globalnej blokady) → 423 termination\_locked (globalna blokada — także dla właściciela) → 403 account\_owner\_required (członek, nawet z manageproducts) → 422 already\_terminated. **Wiązanie domeny skrzynki.** Operacje pocztowe wykonujemy w DirectAdmin poświadczeniami administracyjnymi, dlatego pole domain przy tworzeniu skrzynki jest ograniczone do domen związanych z tym kontem hostingowym: domeny głównej konta hostingowego, **aktywnych domen tego samego konta klienta** oraz domen skrzynek już zsynchronizowanych z DA na tym koncie hostingowym. Porównanie jest dokładne (niewrażliwe na wielkość liter i kropkę końcową) — subdomena musi sama znajdować się na tej liście. Domena spoza listy jest odrzucana (422 w API, błąd narzędzia w MCP) — bez tego można byłoby założyć skrzynkę na domenie innego klienta z tego samego serwera. ## Bezpieczeństwo danych wrażliwych **Hasła skrzynek e-mail są wyłącznie do zapisu (write-only): przyjmowane w payloadzie tworzenia/edycji, przekazywane wprost do API DirectAdmin, nigdy nieprzechowywane lokalnie i nigdy niezwracane w żadnej odpowiedzi.** Hasło panelu DA (encrypted\_password), klucze logowania SSO oraz hostname/IP/port i poświadczenia API serwera DA są celowo nigdy nieserializowane — konto ujawnia jedynie lokalizację. Kolumny wewnętrzne kopii (local\_path, restore\_log) także nie są eksponowane. ## Efekty uboczne — asynchroniczne i stan konta Efekty po stronie DirectAdmin (tworzenie/przywracanie kopii, wydanie SSL, terminacja) działają out-of-band przez zadania kolejki, jak w web — akcje zwracają 202 Accepted. Przywrócenie kopii wymaga dodatkowo potwierdzenia e-mailem przez właściciela konta (patrz niżej). Tworzenie/usuwanie/edycja skrzynek woła API DA synchronicznie, a lokalny mirror odświeża SyncEmailAccountsJob. Każda operacja sięgająca backendu DA wymaga **aktywnego** konta: konto pending jeszcze się provisionuje, a terminated nie przyjmie już akcji — w obu przypadkach API zwraca 409 Conflict. ## Przywrócenie kopii — potwierdzenie e-mailem Przywrócenie nadpisuje pliki, pocztę i bazy konta, więc ani API v1, ani MCP **nie przywracają od razu**. Żądanie tylko zleca przywrócenie: Nodea wysyła do **właściciela konta klienta** e-mail z podpisanym, jednorazowym linkiem ważnym 30 minut (ten sam przepływ co w panelu). Przywrócenie trafia do kolejki dopiero wtedy, gdy właściciel otworzy link, będąc zalogowanym do Nodea. Sam token — nawet ze scope account:delete — nie wystarczy. - Odpowiedź: 202 Accepted z data.status = "pending\_confirmation", data.backup\_id i data.confirmation\_ttl\_minutes (30). - Nowe żądanie dla tego samego konta unieważnia wcześniejsze, niewykorzystane linki — działa tylko najnowszy. - Link otwarty przez innego użytkownika niż właściciel, po czasie lub drugi raz nic nie przywraca. - Postęp po potwierdzeniu sprawdzisz na liście kopii (GET …/backups, pole status). { "message": "Restore requested. The account owner must confirm it with the link sent by e-mail.", "data": { "status": "pending\_confirmation", "backup\_id": 128, "confirmation\_ttl\_minutes": 30 } } ## API v1 — endpointy MetodaŚcieżkaScopeOpisGET/api/v1/hostingaccount:readLista kont hostingowych bieżącego konta (id malejąco), paginowana. GET/api/v1/hosting/{account}account:readSzczegóły konta: użycie dysku/transferu, SSL, lokalizacja, plan, znaczniki czasu. GET/api/v1/hosting/{account}/emailsaccount:readLista skrzynek e-mail konta (po adresie), paginowana — per\_page 1–100 (domyślnie 20), page. POST/api/v1/hosting/{account}/emailsaccount:writeUtworzenie skrzynki (hasło write-only). Zwraca 202. PATCH/api/v1/hosting/{account}/emails/{email}account:writeZmiana hasła (write-only) i/lub quota skrzynki. Nie dla skrzynki systemowej \@\ — 409 system\_mailbox\_locked. DELETE/api/v1/hosting/{account}/emails/{email}account:writeUsunięcie skrzynki (DA + lokalnie, nieodwracalne). Wymaga confirm: true w ciele (inaczej 422). Nie dla skrzynki systemowej — 409 system\_mailbox\_locked. Zwraca 204. GET/api/v1/hosting/{account}/backupsaccount:readLista kopii zapasowych konta (id malejąco), paginowana. POST/api/v1/hosting/{account}/backupsaccount:writeZlecenie nowej kopii (nazwa backup-Y-m-d-H-i). Zwraca 202. POST/api/v1/hosting/{account}/backups/{backup}/restoreaccount:deleteZlecenie przywrócenia kopii — nadpisze stan konta (nieodwracalne). Nie przywraca od razu: zwraca 202 ze statusem pending\_confirmation, a przywrócenie rusza po kliknięciu linku z e-maila przez właściciela konta. POST/api/v1/hosting/{account}/sslaccount:writeZlecenie wydania certyfikatu Let's Encrypt. Wymaga konta aktywnego. Zwraca 202. DELETE/api/v1/hosting/{account}account:deleteTerminacja konta (destrukcyjna, async) — tylko właściciel konta klienta. Zwraca 202. Kolejność błędów: 404 → 423 (managed\_by\_whmcs) → 423 (termination\_locked) → 403 (account\_owner\_required) → 422 (already\_terminated). **Wyłącznie web (poza API i MCP):** logowanie SSO do panelu DirectAdmin (mint klucza logowania) oraz reset hasła konta — to interaktywne przekazania do przeglądarki, nie operacje headless. ### Skrzynki e-mail — parametry ciała - email\_local (string, wymagany przy tworzeniu, 1–64 znaki, charset \[a-zA-Z0-9.\_-\]) — część lokalna adresu. - domain (string, wymagany przy tworzeniu, 4–253, kształt FQDN) — **musi należeć do konta**: domena główna konta hostingowego, aktywna domena tego samego konta klienta albo domena istniejącej skrzynki tego konta hostingowego. - password (string, 10–128 znaków; wymagany przy tworzeniu, opcjonalny przy edycji) — **write-only**. - quota\_mb (int 50–10000; wymagany przy tworzeniu, opcjonalny przy edycji). **Usuwanie skrzynki** (DELETE …/emails/{email}): ciało {"confirm": true} (albo ?confirm=1). Kolejność kontroli: 404 (skrzynka lub konto poza bieżącym kontem) → 422 (brak potwierdzenia) → 409 (konto nieaktywne) → 409 system\_mailbox\_locked. ### Konto hostingowe — pola i limity Konto (HostingAccountResource; to samo w MCP hosting-list / hosting-get): id, account\_id, domain, username, status, package, disk\_used\_mb, disk\_quota\_mb, bandwidth\_used\_mb, bandwidth\_quota\_mb, inode\_quota, disk\_usage\_percent, bandwidth\_usage\_percent, inodes\_used, limits, limits\_synced\_at, ssl\_enabled, ssl\_expires\_at, daty cyklu życia, location, plan, next\_due\_at. Nigdy nie zawiera hasła panelu ani danych serwera DA. Limity są synchronizowane z DirectAdmin (razem ze zużyciem, co kilka godzin). disk\_quota\_mb, bandwidth\_quota\_mb i inode\_quota to liczba albo null — **null nie oznacza zera**: to „bez limitu” albo „brak danych”. Rozstrzyga obiekt limits z kluczami disk\_mb, bandwidth\_mb, inodes, email\_accounts, databases, domains, subdomains, ftp\_accounts; każda wartość to liczba, napis "unlimited" (bez limitu) albo null (limit nieznany). limits\_synced\_at = null oznacza, że limitów jeszcze nie pobrano. \*\_usage\_percent wynosi 0, gdy limit jest nieznany lub nieograniczony. **Zmiana kontraktu (2026-09):** disk\_quota\_mb i bandwidth\_quota\_mb były wcześniej zawsze liczbą (brak limitu serializowano jako 0); teraz są nullable. Doszły pola inode\_quota, limits, limits\_synced\_at. { "disk\_used\_mb": 2760, "disk\_quota\_mb": 10240, "bandwidth\_used\_mb": 5120, "bandwidth\_quota\_mb": null, "inode\_quota": null, "limits": { "disk\_mb": 10240, "bandwidth\_mb": "unlimited", "inodes": null, "email\_accounts": 10, "databases": 5, "domains": 1, "subdomains": "unlimited", "ftp\_accounts": 5 }, "limits\_synced\_at": "2026-09-26T08:00:00+00:00" } Skrzynka (HostingEmailResource): id, email, domain, quota\_mb, used\_mb, is\_forwarder, forward\_to, is\_active, last\_synced\_at — nigdy nie zawiera pola hasła. Kopia (HostingBackupResource): id, backup\_name, size\_mb, status, is\_remote, created\_at, expires\_at, restore\_url (link do akcji restore). ### Kody błędów - 401 — brak/niepoprawny token. - 403 — brak wymaganego scope. - 403 — błąd kontekstu konta: account\_permission\_denied (pole permission podaje brakującą flagę) — products przy odczycie, manageproducts przy akcjach, no\_account\_context, account\_forbidden / account\_mismatch (nagłówek X-Account-Id lub przypięcie tokenu) — patrz [Konta klientów](https://nodea.pl/pl/dokumentacja-api/accounts). - 403 — account\_owner\_required: terminację może zlecić tylko właściciel konta klienta. - 404 — nieznane konto hostingowe, skrzynka lub kopia albo zasób spoza bieżącego konta. - 409 — konto nie jest aktywne (pending/terminated) dla akcji sięgającej backendu DA. - 409 — system\_mailbox\_locked: skrzynki systemowej \@\ (jej hasło to hasło konta DA) nie można zmienić (PATCH) ani usunąć (DELETE). - 422 — walidacja (w tym domena skrzynki spoza konta, brak confirm: true przy usuwaniu skrzynki oraz per\_page powyżej 100) lub próba terminacji już zterminowanego konta (kod already\_terminated). - 423 — terminacja konta zarządzanego w panelu rozliczeń WHMCS jest odrzucana zawsze, także przy wyłączonej blokadzie globalnej (kod managed\_by\_whmcs); konto pozostaje nietknięte — usługę zamyka się w panelu rozliczeń. - 423 — terminacja jest obecnie zablokowana globalnie w Nodea (kod termination\_locked); konto pozostaje nietknięte. Blokada jest sprawdzana przed uprawnieniami konta. Cykl życia usług prowadzi system rozliczeń — skontaktuj się z pomocą techniczną. ## Przykłady — API ### Lista kont hostingowych curl -s "https://app.nodea.io/api/v1/hosting?per\_page=20" \\ -H "Authorization: Bearer $NODEA\_TOKEN" \\ -H "Accept: application/json" ### Utworzenie skrzynki e-mail (hasło write-only) curl -s -X POST https://app.nodea.io/api/v1/hosting/{account}/emails \\ -H "Authorization: Bearer $NODEA\_TOKEN" \\ -H "Content-Type: application/json" \\ -d '{ "email\_local": "biuro", "domain": "moja-domena.pl", "password": "TajneHaslo123!", "quota\_mb": 2000 }' ### Zlecenie kopii zapasowej curl -s -X POST https://app.nodea.io/api/v1/hosting/{account}/backups \\ -H "Authorization: Bearer $NODEA\_TOKEN" \\ -H "Accept: application/json" ### Zlecenie przywrócenia kopii (nieodwracalne, potwierdzane e-mailem) curl -s -X POST https://app.nodea.io/api/v1/hosting/{account}/backups/{backup}/restore \\ -H "Authorization: Bearer $NODEA\_TOKEN" \\ -H "Accept: application/json" ## MCP — narzędzia Narzędzia MCP dzielą model uwierzytelniania i zakresów z API v1 (Bearer + scope w ensureScope) oraz flagę hosting-suite (narzędzie na nieaktywnej fladze znika z tools/list). Identyfikatory to liczby całkowite. Brakujący i cudzy identyfikator zwracają ten sam błąd. Akcje sięgające DirectAdmin są asynchroniczne (zwracają potwierdzenie zlecenia). Narzędzia niszczące — hosting-backup-restore i hosting-terminate — są oznaczone jako destructive i wymagają jawnego confirm: true; hosting-email-delete też wymaga confirm: true. hosting-backup-restore nie przywraca od razu: zwraca status: "pending\_confirmation" (queued: false), a przywrócenie rusza po potwierdzeniu linkiem z e-maila przez właściciela konta (jak w API v1). Systemowej skrzynki \@\ (jej hasło to hasło konta DA) nie można zmienić ani usunąć — błąd z sufiksem (code: system\_mailbox\_locked). Hasła skrzynek pozostają write-only. Reguły walidacji skrzynek (charset części lokalnej, hasło 10–128 znaków, quota 50–10000 MB, wiązanie domeny z kontem) są **wspólne z API v1** — MCP nie jest łagodniejszą furtką do tych samych operacji. NazwaScopeTrybOpishosting-listaccount:readread-onlyLista kont DirectAdmin (id malejąco); page, per\_page (max 50). hosting-getaccount:readread-onlySzczegóły konta po id. Hasło panelu DA nigdy nie jest zwracane. hosting-emailsaccount:readread-onlyLista skrzynek konta (po adresie); account\_id, page, per\_page (max 50). hosting-email-createaccount:writezapisUtworzenie skrzynki; account\_id, email\_local, domain (musi należeć do konta — domena główna konta hostingowego, aktywna domena tego samego konta klienta lub domena już zsynchronizowanej skrzynki), password (write-only, 10–128 znaków), quota\_mb (50–10000). Konto musi być aktywne. hosting-email-updateaccount:writezapisZmiana hasła (write-only, 10–128 znaków) i/lub quota (50–10000); account\_id, email\_id, password?, quota\_mb?. Nie dla skrzynki systemowej (system\_mailbox\_locked). hosting-email-deleteaccount:writezapis (confirm)Usunięcie skrzynki (DA + lokalnie, nieodwracalne). Wymaga confirm: true; account\_id, email\_id. Nie dla skrzynki systemowej (system\_mailbox\_locked). Konto musi być aktywne. hosting-backupsaccount:readread-onlyLista kopii konta (id malejąco); account\_id, page, per\_page (max 50). hosting-backup-createaccount:writezapisZlecenie kopii; account\_id. Async — odpytuj hosting-backups. Konto musi być aktywne. hosting-backup-restoreaccount:deletedestrukcyjne (confirm)Zlecenie przywrócenia kopii — nadpisze dane konta. Wymaga confirm: true; account\_id, backup\_id. Zwraca {queued: false, status: "pending\_confirmation", backup\_id, confirmation\_ttl\_minutes}; przywrócenie rusza po kliknięciu linku z e-maila przez właściciela konta (30 min, jednorazowy, nowe zlecenie unieważnia poprzednie). hosting-issue-sslaccount:writezapisZlecenie certyfikatu Let's Encrypt; account\_id. Async — odpytuj hosting-get. Konto musi być aktywne. hosting-terminateaccount:deletedestrukcyjne (confirm)Terminacja konta — nieodwracalne. Wymaga confirm: true; account\_id. Async. Tylko właściciel konta klienta. Kolejność błędów: nie znaleziono → managed\_by\_whmcs (konto zarządzane w WHMCS — zawsze, nic nie jest zlecane) → termination\_locked (globalna blokada, nic nie jest zlecane) → account\_owner\_required → already\_terminated. **Konta klientów w MCP.** Narzędzia działają w bieżącym koncie połączenia MCP (patrz [Konta klientów](https://nodea.pl/pl/dokumentacja-api/accounts)). hosting-list, hosting-get, hosting-emails i hosting-backups wymagają uprawnienia products; hosting-email-create/-update/-delete, hosting-backup-create/-restore i hosting-issue-ssl — products + manageproducts; hosting-terminate — roli właściciela. Odmowy kończą się sufiksem (code: account\_permission\_denied, permission: \), (code: account\_owner\_required), (code: no\_account\_context), (code: managed\_by\_whmcs), (code: termination\_locked) lub (code: already\_terminated). ### Przykłady — MCP (JSON-RPC) { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "hosting-email-create", "arguments": { "account\_id": 7, "email\_local": "biuro", "domain": "moja-domena.pl", "password": "TajneHaslo123!", "quota\_mb": 2000 } } } { "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "hosting-backup-restore", "arguments": { "account\_id": 7, "backup\_id": 128, "confirm": true } } } Odpowiedź (structuredContent) — przywrócenie czeka na potwierdzenie e-mailem przez właściciela konta: { "queued": false, "status": "pending\_confirmation", "backup\_id": 128, "confirmation\_ttl\_minutes": 30 } ## Powiązane - [Domeny — API v1 i MCP | Dokumentacja Nodea](https://nodea.pl/pl/dokumentacja-api/domains) - [Migrator — API v1 i MCP | Dokumentacja Nodea](https://nodea.pl/pl/dokumentacja-api/migrations) - [Konta klientów — API v1 i MCP | Dokumentacja Nodea](https://nodea.pl/pl/dokumentacja-api/accounts) --- Wersje językowe: [en](https://nodea.io/en/api-docs/hosting.md) Spis treści witryny: [llms.txt](https://nodea.pl/pl/llms.txt)