--- title: "Domeny — API v1 i MCP | Dokumentacja Nodea" description: "Pełny reference modułu Domeny: endpointy REST API v1 (lista, szczegóły, zmiana nameserverów, WHOIS privacy, żądanie kodu EPP), zakres account:*, narzędzia MCP oraz przykłady curl i JSON-RPC." url: "https://nodea.pl/pl/dokumentacja-api/domains" lang: "pl" updated: "2026-07-16" --- # Domeny — API v1 i MCP | Dokumentacja Nodea > Reference modułu Domeny — endpointy API v1 (lista z filtrem, szczegóły z kontaktami WHOIS, zmiana nameserverów, WHOIS privacy, żądanie kodu EPP), zakres account:read/write, narzędzia MCP i przykłady. Rejestracja i transfery pozostają web-only. Moduł **Domeny** obejmuje zarejestrowane domeny konta klienta: listowanie z filtrem, szczegóły wraz z kontaktami WHOIS oraz operacje utrzymaniowe — zmianę nameserverów, przełączanie prywatności WHOIS i żądanie kodu autoryzacji transferu (EPP). 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: - account:read — listowanie i podgląd (index, show). - account:write — edycja nameserverów oraz akcje niedestrukcyjne (WHOIS privacy, żądanie EPP). Cały moduł jest dodatkowo bramkowany flagą Pennant features:hosting-suite — wyłączenie ukrywa go zarówno w web UI, jak 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 tej samej flagi hosting-suite. ## Konto klienta, własność i widoczność Domeny 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 /domains, GET /domains/{domain}domains PATCH /domains/{domain}, POST /domains/{domain}/whois-privacy, POST /domains/{domain}/eppdomains + managedomains Lista zwraca wyłącznie domeny **bieżącego konta**, a DomainResource niesie pole account\_id. Domena spoza bieżącego konta — innego klienta albo innego Twojego konta — oraz nieznany identyfikator zwracają konsekwentnie 404 (a nie 403), więc API nigdy nie potwierdza istnienia obcej domeny. Członek bez uprawnienia dostaje 403 account\_permission\_denied z polem permission (domains albo managedomains). W MCP zasobom spoza konta odpowiada jeden komunikat „nie znaleziono lub brak dostępu”, uniemożliwiający enumerację identyfikatorów między najemcami. ## Bezpieczeństwo danych wrażliwych **Kod EPP / auth-info jest tylko do zapisu-po-stronie-serwera i nigdy nie wraca przez API ani MCP.** Trzymany jest w kolumnie zaszyfrowanej i ukrytej na modelu; wypełnia go asynchronicznie zadanie TransferDomainOutJob. Odczytać go można wyłącznie w portalu web. Podobnie **PESEL** kontaktu WHOIS jest zaszyfrowany i ukryty — kontakty zwracają tylko imię, nazwisko, firmę, adres oraz identyfikatory NIP/REGON, nigdy PESEL. Wewnętrzne dane rejestratora (registrar\_data) również pozostają ukryte. ## Efekty uboczne — asynchroniczne Wszystkie operacje sięgające do rejestratora (zmiana nameserverów, przełącznik WHOIS privacy, żądanie EPP) działają out-of-band przez kolejkę zadań, dokładnie jak w przepływie web: endpoint waliduje wejście, zapisuje stan lokalny i dispatchuje zadanie, a runda HTTP do rejestratora dzieje się w workerze. Dlatego akcje zwracają 202 Accepted („zadanie w kolejce”), a nie natychmiastowy wynik. ## API v1 — endpointy MetodaŚcieżkaScopeOpisGET/api/v1/domainsaccount:readLista domen bieżącego konta (id malejąco), paginowana. Filtry status, q. GET/api/v1/domains/{domain}account:readSzczegóły domeny: nameservery, okres, kod EPP (null do czasu żądania) i cztery kontakty WHOIS. PATCH/api/v1/domains/{domain}account:writeZmiana auto\_renew i/lub nameserverów. Zadanie rejestratora rusza tylko, gdy efektywny zestaw NS się zmieni. POST/api/v1/domains/{domain}/whois-privacyaccount:writeWłącz/wyłącz prywatność WHOIS (enabled bool). Wymaga statusu Active. 202/422. POST/api/v1/domains/{domain}/eppaccount:writeŻądanie kodu EPP do transferu wychodzącego. Wymaga zdatności do transferu (Active + 60 dni). 202/422. **Wyłącznie web (poza API i MCP):** wyszukiwanie dostępności domen, zamówienie/rejestracja oraz transfer przychodzący (transfer-in) — to wieloetapowe kreatory zbierające dane kontaktowe, nieprzystające do wywołania headless. ### GET /domains — parametry zapytania - status (enum, opcjonalny) — jedna z wartości: pending, active, expired, redemption, transferred\_out, transferring\_in, pending\_delete, cancelled (cancelled — anulowana lub oznaczona jako fraud w WHMCS; tylko domeny rozliczane w WHMCS). - q (string, opcjonalny, max 255) — dopasowanie po sld lub tld (LIKE). - per\_page (int 1–100, domyślnie 20), page (int ≥1). Wiersz listy (DomainResource): id, full\_domain, sld, tld, status, registered\_at, expires\_at, days\_until\_expiry, auto\_renew, whois\_privacy\_enabled. Szczegóły (show) dokładają: period\_years, nameservers\[\], epp\_code (null do czasu żądania), can\_transfer\_out oraz registrant/admin/tech/billing (kontakty WHOIS). ### PATCH /domains/{id} — parametry ciała - auto\_renew (bool, opcjonalny). - nameservers (tablica 0–4, opcjonalna) — hostnamy w kształcie FQDN (regex, max 253 znaki). Pusta tablica resetuje NS do domyślnych platformy. Oba klucze są niezależne — można zmienić samo auto\_renew albo same nameservery. Zadanie UpdateDomainNameserversJob dispatchuje się tylko, gdy efektywny zestaw NS faktycznie się zmieni (ten sam short-circuit co w web). ### 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ę) — domains przy odczycie, managedomains 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). - 404 — nieznana domena albo domena spoza bieżącego konta. - 422 — walidacja lub stan domeny: WHOIS privacy poza Active (kod domain\_not\_active), EPP dla domeny niezdatnej do transferu (kod domain\_not\_transferable). ## Przykłady — API ### Lista aktywnych domen curl -s "https://app.nodea.io/api/v1/domains?status=active&per\_page=20" \\ -H "Authorization: Bearer $NODEA\_TOKEN" \\ -H "Accept: application/json" ### Zmiana nameserverów curl -s -X PATCH https://app.nodea.io/api/v1/domains/{id} \\ -H "Authorization: Bearer $NODEA\_TOKEN" \\ -H "Content-Type: application/json" \\ -d '{ "nameservers": \["ns1.example.com", "ns2.example.com"\] }' ### Włączenie prywatności WHOIS curl -s -X POST https://app.nodea.io/api/v1/domains/{id}/whois-privacy \\ -H "Authorization: Bearer $NODEA\_TOKEN" \\ -H "Content-Type: application/json" \\ -d '{ "enabled": true }' ### Żądanie kodu EPP (transfer wychodzący) curl -s -X POST https://app.nodea.io/api/v1/domains/{id}/epp \\ -H "Authorization: Bearer $NODEA\_TOKEN" \\ -H "Accept: application/json" # 202 Accepted — kod EPP nie wraca w odpowiedzi; odczytasz go w portalu web. ## MCP — narzędzia Narzędzia MCP dzielą model uwierzytelniania i zakresów z API v1 (Bearer + scope sprawdzany w ensureScope) oraz flagę hosting-suite (narzędzie na nieaktywnej fladze znika z tools/list). Identyfikator domeny to liczba całkowita. Brakujący i cudzy identyfikator zwracają ten sam błąd (brak enumeracji między najemcami). Akcje sięgające rejestratora są asynchroniczne — narzędzie zwraca potwierdzenie zlecenia, nie finalny wynik. Kod EPP nigdy nie jest zwracany. NazwaScopeTrybOpisdomains-listaccount:readread-onlyLista domen (id malejąco). Filtr status (kubełki: all, active, expiring = Active + wygasa w 30 dni, expired = expired/redemption, pending = pending/transferring\_in), wyszukiwanie q, page, per\_page (max 50). domain-getaccount:readread-onlySzczegóły domeny z kontaktami WHOIS i flagą can\_transfer\_out. Param: id. Kod EPP nie jest serializowany. domain-set-nameserversaccount:writeidempotentnePodmiana nameserverów (nameservers, 1–4 hostnamy). Zapis natychmiastowy, push do rejestratora async. Zwraca zaktualizowaną listę NS. domain-whois-privacyaccount:writeidempotentneWłącz/wyłącz prywatność WHOIS (enabled bool). Tylko dla domeny Active. Push do rejestratora async. domain-request-eppaccount:writeidempotentneŻądanie kodu EPP do transferu wychodzącego. Tylko po zdjęciu 60-dniowej blokady ICANN. Kod nigdy nie wraca — odczyt w portalu web. **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)). domains-list i domain-get wymagają uprawnienia domains; domain-set-nameservers, domain-whois-privacy i domain-request-epp — domains + managedomains. Lista obejmuje tylko domeny bieżącego konta. Odmowa kończy się sufiksem (code: account\_permission\_denied, permission: \) lub (code: no\_account\_context). ### Przykłady — MCP (JSON-RPC) { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "domain-set-nameservers", "arguments": { "id": 42, "nameservers": \["ns1.example.com", "ns2.example.com"\] } } } { "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "domain-request-epp", "arguments": { "id": 42 } } } ## Powiązane - [Hosting](https://nodea.pl/pl/slownik-pojec/hosting) - [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/domains.md) Spis treści witryny: [llms.txt](https://nodea.pl/pl/llms.txt)