Domeny — API v1 i MCP | Dokumentacja API Nodea

Moduł Domeny obejmuje zarejestrowane domeny użytkownika: 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 <token>. 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.

Własność i widoczność (ownership)

Domeny nie mają klasy polityki i nie są współdzielone — każdy dostęp do wiersza jest twardo ograniczony do właściciela przez user_id. Cudzy lub nieznany identyfikator zwraca konsekwentnie 404 (a nie 403), więc API nigdy nie potwierdza istnienia obcej domeny. W MCP odpowiada temu 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żka	Scope	Opis
GET	/api/v1/domains	account:read	Lista domen właściciela (id malejąco), paginowana. Filtry `status`, `q`.
GET	/api/v1/domains/{domain}	account:read	Szczegóły domeny: nameservery, okres, kod EPP (null do czasu żądania) i cztery kontakty WHOIS.
PATCH	/api/v1/domains/{domain}	account:write	Zmiana `auto_renew` i/lub nameserverów. Zadanie rejestratora rusza tylko, gdy efektywny zestaw NS się zmieni.
POST	/api/v1/domains/{domain}/whois-privacy	account:write	Włącz/wyłącz prywatność WHOIS (`enabled` bool). Wymaga statusu Active. `202`/`422`.
POST	/api/v1/domains/{domain}/epp	account: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.
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.
404 — nieznana lub cudza domena.
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.

Nazwa	Scope	Tryb	Opis
domains-list	account:read	read-only	Lista 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-get	account:read	read-only	Szczegóły domeny z kontaktami WHOIS i flagą `can_transfer_out`. Param: `id`. Kod EPP nie jest serializowany.
domain-set-nameservers	account:write	idempotentne	Podmiana nameserverów (`nameservers`, 1–4 hostnamy). Zapis natychmiastowy, push do rejestratora async. Zwraca zaktualizowaną listę NS.
domain-whois-privacy	account:write	idempotentne	Włącz/wyłącz prywatność WHOIS (`enabled` bool). Tylko dla domeny Active. Push do rejestratora async.
domain-request-epp	account:write	idempotentne	Żądanie kodu EPP do transferu wychodzącego. Tylko po zdjęciu 60-dniowej blokady ICANN. Kod nigdy nie wraca — odczyt w portalu web.

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 }
  }
}

Domeny — API v1 i MCP | Dokumentacja Nodea