--- title: "API Nodea v1 — wprowadzenie: base URL, tokeny, scope'y, limity | Nodea" description: "Wprowadzenie do API Nodea v1: base URL /api/v1, token Passport (Bearer), 12 scope'ów, konta klientów i nagłówek X-Account-Id, rate limit 240/min, format błędów i paginacja." url: "https://nodea.pl/pl/dokumentacja-api/overview" lang: "pl" updated: "2026-07-16" --- # API Nodea v1 — wprowadzenie: base URL, tokeny, scope'y, limity | Nodea > REST API Nodea v1 daje programowy dostęp do monitoringu, alertów, infrastruktury i konta. Poznaj base URL, uwierzytelnianie tokenem, scope'y, limity zapytań, błędy i paginację. API Nodea (wersja **v1**) daje programowy dostęp do tego samego, co panel /app: monitoringu stron i heartbeatów, integracji i eskalacji alertów, serwerów, kluczy SSH, stref DNS, urządzeń Vault oraz konta (profil, zgłoszenia, rozliczenia, domeny, hosting, migracje). Interfejs jest w pełni REST-owy, przyjmuje i zwraca JSON, a każdy zasób jest ograniczony do właściciela tokenu — zasoby handlowe (zgłoszenia, rozliczenia, domeny, DNS, hosting, maszyny wirtualne) do **bieżącego konta klienta** (patrz sekcja „Konta klientów”). Ten wpis to **wprowadzenie** — opisuje bazowy adres, uwierzytelnianie, zakresy uprawnień (scope'y), limity zapytań, format błędów i paginację. Dokumentacja poszczególnych modułów (endpointy, pola, przykłady) znajduje się w osobnych wpisach tej kolekcji. ## Base URL Wszystkie ścieżki API v1 są względem jednego prefiksu: https://app.nodea.io/api/v1 Na przykład endpoint tożsamości tokenu to GET /api/v1/me, a lista monitorowanych stron — GET /api/v1/websites. Wszystkie odpowiedzi mają Content-Type: application/json. Wysyłając dane, ustaw nagłówki Accept: application/json oraz Content-Type: application/json. ## Uwierzytelnianie API v1 chroni guard Passport (auth:api). Autoryzujesz się **Personal Access Tokenem** (PAT) — długoterminowym tokenem OAuth, który wygenerujesz sam w panelu. ### Jak wygenerować token 1. Zaloguj się do panelu i wejdź w [ustawienia konta](https://nodea.pl/pl/dokumentacja-api) → **Tokeny API** (/app/account/api-tokens). 2. Kliknij **Utwórz token**, nadaj mu nazwę i zaznacz tylko te **scope'y**, których dana integracja naprawdę potrzebuje. 3. Skopiuj pełną wartość tokenu **od razu** — jest pokazywana tylko raz. Później w panelu widoczna jest wyłącznie nazwa i lista scope'ów. ### Nagłówek autoryzacji Token dołączasz do każdego żądania w nagłówku Authorization jako Bearer: Authorization: Bearer 1|AbCdEf0123456789... Żądanie bez ważnego tokenu — lub z tokenem odwołanym — otrzyma 401 Unauthorized. Token możesz w każdej chwili unieważnić w panelu; unieważnienie działa natychmiast. ## Scope'y (zakresy uprawnień) Token nie daje pełnego dostępu do konta — niesie tylko te uprawnienia, które zaznaczysz przy jego tworzeniu. Scope'y są zorganizowane w **4 grupy modułowe**, każda w trzech poziomach: read (listowanie i odczyt), write (tworzenie, aktualizacja i akcje nieniszczące — np. „uruchom teraz", pauza, test powiadomienia) oraz delete (akcje **nieodwracalne** — usunięcie zasobu, zatrzymanie VM, terminacja hostingu). Łącznie daje to **12 scope'ów** (4 grupy × 3 poziomy) plus jeden wąski scope specjalny dns:acme — razem 13: GrupaScope'yCo autoryzuje **monitoring**monitoring:read monitoring:write monitoring:deleteStrony (websites), heartbeaty, raporty i strony statusu (status pages). *read* = listy i szczegóły; *write* = tworzenie/edycja, „uruchom teraz", pauza/wznowienie, okna serwisowe; *delete* = usunięcie monitora wraz z historią. **alerting**alerting:read alerting:write alerting:deleteIntegracje powiadomień, grupy powiadomień, polityki eskalacji i udostępnienia (sharing). *write* obejmuje test powiadomienia; *delete* = usunięcie integracji/polityki/udostępnienia. **infra**infra:read infra:write infra:deleteSerwery, klucze SSH, strefy DNS i urządzenia Vault. *write* = tworzenie/edycja i akcje operacyjne; *delete* = akcje niszczące, np. zatrzymanie VM czy usunięcie klucza/strefy. **dns**dns:acmeWyłącznie automatyzacja certyfikatów DNS-01: wyszukanie strefy po nazwie oraz dodawanie i usuwanie rekordów TXT \_acme-challenge.\*. Bez odczytu stref i rekordów, bez innych typów i nazw rekordów, bez dostępu do reszty API (wyjątek: GET /api/v1/me i narzędzie MCP whoami, dostępne dla każdego tokenu poza tokenem wtyczki nodeaD, zwracają profil właściciela i bieżące konto) — patrz [DNS — automatyzacja DNS-01](https://nodea.pl/pl/dokumentacja-api/dns#dns-01). **fleet** (tylko OAuth)fleet:enrollJednorazowe podłączenie serwera przyciskiem „Połącz z panelem nodea” we wtyczce nodeaD (DirectAdmin / cPanel / WHM): wydanie pakietu startowego agenta dla istniejącego serwera wybranego przez użytkownika na ekranie zgody. Zarezerwowany dla klienta OAuth „nodeaD server plugin” — **nie da się go nadać tokenowi osobistemu** i nie wlicza się do 13 powyżej; token działa wyłącznie na POST /api/v1/fleet/enrollments (każda inna trasa, także GET /api/v1/me i MCP whoami, odpowiada 403 token\_restricted) i jest unieważniany po pierwszym użyciu — patrz [Podłączanie serwerów wtyczką nodeaD](https://nodea.pl/pl/dokumentacja-api/fleet-enrollments). **account**account:read account:write account:deleteProfil, zgłoszenia (tickety), rozliczenia (billing), zmiana planu usług, domeny, hosting i migrator. *delete* = akcje nieodwracalne, np. terminacja hostingu. Zasada jest prosta: **nadawaj tokenowi minimum uprawnień**. Integracja tylko odczytująca status monitoringu potrzebuje wyłącznie monitoring:read — nie dawaj jej :write ani :delete. Endpoint dziedziczy też te same flagi funkcji (Pennant) co panel, więc jeśli moduł jest wyłączony dla Twojego konta, token go nie odblokuje. Żądanie tokenem bez wymaganego scope'a otrzyma 403 Forbidden. ## Konta klientów Zasoby handlowe — **zgłoszenia, rozliczenia (faktury, portfele, transakcje), domeny, strefy DNS, konta hostingowe i serwery z maszyną wirtualną** — należą do **konta klienta**, a nie bezpośrednio do użytkownika. Konto może mieć wielu użytkowników: jednego **właściciela** (owner) i dowolną liczbę **członków** (member) z indywidualnie nadanymi uprawnieniami. Każdy użytkownik ma swoje konto osobiste i może dodatkowo należeć do kont innych klientów (np. firmy, dla której pracuje). Konto jest rozliczane przez Nodea (billing\_source: nodea), przez system WHMCS (billing\_source: whmcs) albo przez Nodea poza panelem — fakturą VAT z wFirma (billing\_source: external). Monitoring (strony, heartbeaty, raporty, strony statusu), alerty, klucze SSH, urządzenia Vault i serwery **bez** maszyny wirtualnej pozostają zasobami osobistymi użytkownika — kontekst konta ich nie zmienia. ### Członkowie i uprawnienia Właściciel ma zawsze wszystkie uprawnienia. Członek ma wyłącznie flagi nadane przez właściciela (nazwy są identyczne jak w WHMCS). Dostępnych jest 13 flag: FlagaZnaczenieCo odblokowuje w API v1 i MCP profileEdycja profilu konta— (panel) contactsPodgląd i zarządzanie kontaktami— (panel) productsPodgląd produktów i usługOdczyt hostingu (konta, skrzynki, kopie) i serwerów z maszyną wirtualną. manageproductsZarządzanie produktami i usługami (wymaga products)Akcje hostingu (skrzynki, kopie, przywracanie, SSL) oraz akcje serwera z VM (edycja, start/stop/reboot VM, WAF, komponenty, klon, test SSH, notatka). productssoLogowanie jednokrotne (SSO) do usług (wymaga products)— (SSO jest wyłącznie w panelu) domainsPodgląd domenOdczyt domen i stref DNS. managedomainsZarządzanie ustawieniami domen (wymaga domains)Nameservery, prywatność WHOIS, żądanie kodu EPP, tworzenie/edycja/usuwanie rekordów DNS. invoicesPodgląd i opłacanie fakturRozliczenia: faktury, portfele, transakcje. quotesPodgląd i akceptacja ofert— (panel) ticketsPodgląd i zakładanie zgłoszeńZgłoszenia: lista, podgląd, tworzenie, odpowiedź, zamknięcie. affiliatesPodgląd i zarządzanie kontem partnerskim— (panel) emailsPodgląd historii wiadomości e-mail— (panel) ordersSkładanie zamówień, zmian pakietów i rezygnacji— (panel) **Efektywny dostęp = scope tokenu ORAZ uprawnienie konta.** Token z account:write należący do członka, który ma domains, ale nie ma managedomains, może czytać domeny, lecz zmiana nameserverów zwróci 403 account\_permission\_denied z polem "permission": "managedomains". I odwrotnie — właściciel z tokenem tylko account:read nadal nie wykona zapisu (403, brak scope'a). Akcje nieodwracalne — terminacja hostingu i usunięcie serwera z maszyną wirtualną — są zarezerwowane dla właściciela i żadna flaga ich nie nadaje (403 account\_owner\_required). ### Kontekst konta (bieżące konto) Każde żądanie API v1 (i każde żądanie do serwera MCP) działa w **jednym bieżącym koncie**. Jest ono ustalane w tej kolejności: 1. **konto, do którego przypięty jest token** — nie da się go zmienić nagłówkiem; 2. nagłówek żądania X-Account-Id: \; 3. **konto domyślne** użytkownika (default\_account\_id); 4. jedyne członkostwo — gdy użytkownik należy do dokładnie jednego konta. Ustalone konto API odsyła w nagłówku odpowiedzi X-Account-Id; brak tego nagłówka oznacza, że żądanie działało bez kontekstu konta. Brak kontekstu nie jest błędem sam w sobie — endpointy, które konta potrzebują, odpowiadają wtedy 403 no\_account\_context. Nagłówek jest weryfikowany na **każdym** endpoincie API v1: niepoprawny lub obcy X-Account-Id zwraca 403 account\_forbidden także np. przy GET /websites. Listy zasobów handlowych (/tickets, /domains, /hosting, /dns/zones, /billing/\*) zwracają wyłącznie zasoby bieżącego konta, a odpowiedzi niosą pole account\_id. Zasób spoza bieżącego konta — nawet należący do innego konta tego samego użytkownika — zwraca 404. Identyfikatory kont, do których należysz, zwraca [GET /api/v1/accounts](https://nodea.pl/pl/dokumentacja-api/accounts). curl -i https://app.nodea.io/api/v1/domains \\ -H "Authorization: Bearer $NODEA\_TOKEN" \\ -H "X-Account-Id: 17" \\ -H "Accept: application/json" HTTP/2 200 Content-Type: application/json X-Account-Id: 17 ... ### Tokeny przypięte do konta Tworząc token w panelu (/app/account/api-tokens) wybierasz konto, w którym token będzie działał — domyślnie to, w którym aktualnie pracujesz w panelu. Token **przypięty** działa wyłącznie w tym koncie: nagłówek X-Account-Id wskazujący inne konto zwraca 403 account\_mismatch, a gdy stracisz dostęp do konta (usunięcie z członków, zamknięcie konta), każde żądanie zwraca 403 account\_forbidden. Opcja **„Dowolne konto (nagłówek X-Account-Id)”** tworzy token nieprzypięty — konto wybiera nagłówek, a bez niego obowiązuje konto domyślne. Lista tokenów w panelu pokazuje przypięte konto albo „Dowolne konto”. **Tokeny utworzone przed wprowadzeniem kont** są nieprzypięte: działają jak „dowolne konto”, więc bez nagłówka trafiają do Twojego konta domyślnego (zwykle konta osobistego) i zachowują się tak jak dotąd. Integracja, która ma działać w innym koncie, powinna wysyłać X-Account-Id albo użyć nowego tokenu przypiętego do tego konta. ### Kody błędów kontekstu konta Błędy konta mają standardowy kształt {message, code}; account\_permission\_denied dokłada pole permission. HTTPKod (code)Kiedy 403account\_forbiddenKonto wskazane nagłówkiem X-Account-Id lub konto, do którego przypięty jest token, nie istnieje, nie jesteś jego członkiem, jest zamknięte albo usunięte; także niepoprawna wartość nagłówka (inna niż dodatnia liczba całkowita). Wszystkie przypadki mają tę samą odpowiedź — API nie potwierdza istnienia cudzych kont. 403account\_mismatchToken jest przypięty do konta, a nagłówek X-Account-Id wskazuje inne konto. 403no\_account\_contextEndpoint wymaga konta, a nie udało się go ustalić (np. należysz do kilku kont, nie masz konta domyślnego i nie wysłałeś nagłówka). 403account\_permission\_deniedTwoje członkostwo w bieżącym koncie nie ma wymaganego uprawnienia. Odpowiedź zawiera dodatkowe pole permission z nazwą brakującej flagi. 403account\_owner\_requiredAkcja jest zarezerwowana dla właściciela konta (terminacja hostingu, usunięcie serwera z maszyną wirtualną) — żadna flaga jej nie nadaje. 423termination\_lockedOperacje niszczące (terminacja hostingu, usunięcie serwera z VM) są globalnie zablokowane. Blokada jest sprawdzana **przed** uprawnieniami konta, więc odpowiada nią także właściciel; zasób pozostaje nietknięty. 423managed\_by\_whmcsZasób (konto hostingowe albo VM serwera) jest zarządzany w panelu rozliczeń WHMCS — jego terminacja lub usunięcie w Nodea jest odrzucane zawsze, niezależnie od globalnej blokady; zasób pozostaje nietknięty. 404—Zasób nie należy do bieżącego konta (także gdy należy do innego Twojego konta) — przełącz konto nagłówkiem X-Account-Id. HTTP/2 403 Content-Type: application/json { "message": "Your role in this account does not grant the 'managedomains' permission.", "code": "account\_permission\_denied", "permission": "managedomains" } ## Rate limit (limit zapytań) API v1 jest ograniczone do **240 żądań na minutę** na token. Licznik jest kluczowany po tokenie (żądania bez tokenu spadają na limit per-IP). Po przekroczeniu limitu otrzymasz 429 Too Many Requests; nagłówki X-RateLimit-Limit, X-RateLimit-Remaining oraz Retry-After podpowiadają, kiedy ponowić żądanie. Buforuj odpowiedzi i nie odpytuj w pętli częściej, niż to konieczne. ## Format błędów Błędy zwracane są jako JSON o kształcie: { "message": "Opis błędu, gotowy do pokazania człowiekowi.", "code": "opcjonalny\_kod\_maszynowy" } Przy błędach walidacji (422) odpowiedź zawiera dodatkowo obiekt errors z listą komunikatów per pole. Kody statusu HTTP, których używa API: KodZnaczenie 400Bad Request — żądanie źle sformułowane. 401Unauthorized — brak tokenu, token nieważny lub odwołany. 403Forbidden — token nie ma wymaganego scope'a, moduł jest wyłączony albo odmowa wynika z kontekstu konta (kody account\_forbidden, account\_mismatch, no\_account\_context, account\_permission\_denied, account\_owner\_required — patrz „Konta klientów”). 404Not Found — zasób nie istnieje, nie należy do właściciela tokenu albo leży poza bieżącym kontem klienta. 409Conflict — akcja koliduje ze stanem zasobu (np. duplikat). 422Unprocessable Entity — błąd walidacji (szczegóły w errors). 423Locked — operacja niszcząca zasób (terminacja hostingu, usunięcie serwera z VM) jest obecnie zablokowana globalnie; kod termination\_locked, zasób pozostaje nietknięty. Blokada jest sprawdzana przed uprawnieniami konta. Zasób zarządzany w panelu WHMCS — zawsze kod managed\_by\_whmcs. 429Too Many Requests — przekroczony rate limit. 502Bad Gateway — błąd usługi zależnej (np. dostawcy infrastruktury). 503Service Unavailable — chwilowa niedostępność (np. tryb serwisowy). ## Paginacja Endpointy zwracające listy są paginowane. Rozmiar strony sterujesz parametrem per\_page (domyślnie **20**, maksymalnie **100**), a numer strony — parametrem page. Odpowiedź niesie tablicę data oraz metadane paginacji (bieżąca strona, liczba stron, łączna liczba rekordów). Endpointy przeglądające bardzo długie historie (np. pojedyncze przebiegi monitoringu) używają **simplePaginate** — zwracają tylko wskaźniki „następna/poprzednia strona" bez zliczania wszystkich rekordów, co jest znacznie tańsze przy milionach wierszy. Iteruj po nich, podążając za linkiem do następnej strony, a nie licząc z góry liczby stron. ## Przykład: curl Najprostszy test tokenu to endpoint GET /api/v1/me, który zwraca tożsamość właściciela tokenu, konto domyślne i bieżące konto klienta (pełny opis w [Konta klientów — API i MCP](https://nodea.pl/pl/dokumentacja-api/accounts)). Bez tokenu — 401: curl -i https://app.nodea.io/api/v1/me HTTP/2 401 Content-Type: application/json { "message": "Unauthenticated." } Z ważnym tokenem — 200: curl -s https://app.nodea.io/api/v1/me \\ -H "Authorization: Bearer 1|AbCdEf0123456789..." \\ -H "Accept: application/json" { "data": { "id": 42, "name": "Jan Kowalski", "email": "jan@example.com", "timezone": "Europe/Warsaw", "currency": "PLN", "default\_account\_id": 17, "current\_account": { "id": 17, "name": "Jan Kowalski", "role": "owner", "permissions": \["profile", "contacts", "products", "manageproducts", "productsso", "domains", "managedomains", "invoices", "quotes", "tickets", "affiliates", "emails", "orders"\], "billing\_source": "nodea", "is\_default": true, "is\_current": true }, "created\_at": "2025-03-01T10:00:00+00:00" } } Gdy to działa, przejdź do dokumentacji konkretnego modułu — każdy opisuje swoje endpointy, parametry i przykłady żądań. ### Jaki jest base URL API Nodea? Wszystkie endpointy API v1 są względem prefiksu https://app.nodea.io/api/v1 — np. GET /api/v1/me albo GET /api/v1/websites. Odpowiedzi są w formacie JSON. ### Jak uzyskać token API? Token (Personal Access Token) wygenerujesz w panelu w sekcji Tokeny API (/app/account/api-tokens). Nadajesz mu nazwę, zaznaczasz potrzebne scope'y i kopiujesz jego wartość — jest pokazywana tylko raz. ### Jak przekazać token w żądaniu? Token dołączasz w nagłówku Authorization jako Bearer, np. Authorization: Bearer 1|AbCd... Żądanie bez ważnego tokenu zwraca 401 Unauthorized. ### Ile jest scope'ów i co obejmują? Jest 12 scope'ów: 4 grupy (monitoring, alerting, infra, account) po 3 poziomy (read/write/delete). read = odczyt, write = tworzenie/edycja i akcje nieniszczące, delete = akcje nieodwracalne. Nadawaj tokenowi tylko niezbędne uprawnienia. ### Jaki jest limit zapytań? 240 żądań na minutę na token. Po przekroczeniu otrzymasz 429 Too Many Requests; nagłówek Retry-After podpowie, kiedy ponowić. ### Jak działa paginacja? Listy są paginowane parametrami per\_page (domyślnie 20, maks. 100) i page. Endpointy z bardzo długą historią używają simplePaginate — iteruj po nich, podążając za linkiem do następnej strony. ### Jak wybrać konto klienta, w którym działa token? Token przypięty do konta działa zawsze w nim. Token nieprzypięty (w tym każdy token sprzed wprowadzenia kont) działa w koncie wskazanym nagłówkiem X-Account-Id, a bez nagłówka — w Twoim koncie domyślnym. Listę kont i ich identyfikatory zwraca GET /api/v1/accounts; bieżące konto API odsyła w nagłówku odpowiedzi X-Account-Id. ## Powiązane - [Serwer MCP Nodea — endpoint, uwierzytelnianie, discovery OAuth, narzędzia | Nodea](https://nodea.pl/pl/dokumentacja-api/mcp) - [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/overview.md) Spis treści witryny: [llms.txt](https://nodea.pl/pl/llms.txt)