--- title: "Konta klientów — API v1 i MCP | Dokumentacja Nodea" description: "Konta klientów w API Nodea: GET /accounts i GET /me, nagłówek X-Account-Id, tokeny przypięte do konta, 13 uprawnień członków, kody błędów account_* oraz narzędzia MCP accounts-list i whoami." url: "https://nodea.pl/pl/dokumentacja-api/accounts" lang: "pl" updated: "2026-09-24" --- # Konta klientów — API v1 i MCP | Dokumentacja Nodea > Reference kont klientów — GET /api/v1/accounts i /me, kontekst konta i nagłówek X-Account-Id, tokeny przypięte do konta, uprawnienia członków, kody błędów account\_\* oraz MCP accounts-list/whoami. Zasoby handlowe Nodea — zgłoszenia, rozliczenia, domeny, strefy DNS, hosting i serwery z maszyną wirtualną — należą do **kont klientów**, do których użytkownik należy jako właściciel albo członek. Ten wpis opisuje, jak integracja odkrywa swoje konta i wybiera to, w którym działa: endpointy GET /api/v1/accounts i GET /api/v1/me, nagłówek X-Account-Id, uprawnienia członków oraz odpowiedniki w MCP (accounts-list, whoami). Zasady ogólne opisuje też sekcja „Konta klientów” we [wprowadzeniu do API](https://nodea.pl/pl/dokumentacja-api/overview). ## Uwierzytelnianie i zakresy (scopes) API v1 uwierzytelnia się osobistym tokenem Passport przez nagłówek Authorization: Bearer \. - GET /api/v1/me — **bez wymaganego scope'a**: każdy ważny token może sprawdzić, kim jest i w jakim koncie działa. - GET /api/v1/accounts — scope account:read. Oba endpointy nie są bramkowane flagą funkcji ani uprawnieniem konta. Limit zapytań: throttle:api-v1 = 240/min na użytkownika tokenu. ## Kontekst konta Każde żądanie działa w **jednym bieżącym koncie**, ustalanym w kolejności: 1. konto, do którego przypięty jest token (nagłówek go nie zmieni — inne konto w nagłówku to 403 account\_mismatch); 2. nagłówek żądania X-Account-Id: \; 3. konto domyślne użytkownika (default\_account\_id); 4. jedyne członkostwo użytkownika. Ustalone konto wraca w nagłówku odpowiedzi X-Account-Id (brak nagłówka = brak kontekstu; endpointy wymagające konta odpowiadają wtedy 403 no\_account\_context). Listy zasobów handlowych zwracają tylko zasoby bieżącego konta, a zasób innego konta — także innego konta tego samego użytkownika — zwraca 404. **Tokeny.** Token tworzony w panelu (/app/account/api-tokens) jest domyślnie przypięty do konta, w którym akurat pracujesz; możesz wybrać inne konto, którego jesteś członkiem, albo opcję „Dowolne konto (nagłówek X-Account-Id)”, która tworzy token nieprzypięty. Tokeny sprzed wprowadzenia kont są nieprzypięte — bez nagłówka działają w koncie domyślnym, tak jak dotąd. ## Uprawnienia członków Właściciel ma wszystkie uprawnienia (w odpowiedziach jego lista permissions zawiera wszystkie 13 flag). Członek ma tylko flagi nadane przez właściciela. Efektywny dostęp to **scope tokenu ORAZ uprawnienie konta**. 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) Akcje zarezerwowane dla właściciela (żadna flaga ich nie nadaje): terminacja konta hostingowego (DELETE /hosting/{id}) i usunięcie serwera z maszyną wirtualną (DELETE /servers/{id}) — członek dostaje 403 account\_owner\_required. ## API v1 — endpointy MetodaŚcieżkaScopeOpisGET/api/v1/accountsaccount:readKonta, do których należy użytkownik tokenu — do wyboru w nagłówku X-Account-Id. Bez paginacji. GET/api/v1/me—Tożsamość użytkownika tokenu, konto domyślne i bieżące konto żądania. ### GET /accounts — odpowiedź Tablica data obiektów AccountResource, najstarsze członkostwo pierwsze. Pomijane są konta **zamknięte i usunięte** (nie da się ich wybrać). Token **przypięty** do konta widzi wyłącznie to jedno konto — nie ujawnia pozostałych kont użytkownika. Lista nie jest paginowana. - id (int) — identyfikator do nagłówka X-Account-Id. - name (string) — nazwa konta. - role (owner|member) — Twoja rola w koncie. - permissions (string\[\]) — flagi, które masz w tym koncie (właściciel: wszystkie 13). - billing\_source (nodea|whmcs|external) — kto rozlicza konto. external = Nodea rozlicza konto poza panelem (faktura VAT z wFirma). Konta WHMCS i external nie mają portfeli Nodea (patrz [Rozliczenia](https://nodea.pl/pl/dokumentacja-api/billing)). - is\_default (bool) — czy to Twoje konto domyślne. - is\_current (bool) — czy to konto, w którym działa bieżące żądanie. Dane rozliczeniowe konta (adres, NIP, PESEL, identyfikatory Stripe/WHMCS) nigdy nie są zwracane. curl -s https://app.nodea.io/api/v1/accounts \\ -H "Authorization: Bearer $NODEA\_TOKEN" \\ -H "Accept: application/json" { "data": \[ { "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 }, { "id": 42, "name": "Acme sp. z o.o.", "role": "member", "permissions": \["products", "domains", "tickets"\], "billing\_source": "whmcs", "is\_default": false, "is\_current": false } \] } ### GET /me — odpowiedź Obiekt UserResource: id, name, email, timezone, currency, created\_at oraz pola kont: - default\_account\_id (int|null) — Twoje konto domyślne (używane, gdy token nie jest przypięty i nie wysłano nagłówka). - current\_account (obiekt|null) — konto, w którym działa **to** żądanie, w kształcie wiersza z GET /accounts; null, gdy konta nie udało się ustalić. Endpoint nie zwraca scope'ów tokenu (zwraca je narzędzie MCP whoami). Odpowiedź niesie nagłówek X-Account-Id z identyfikatorem bieżącego konta. curl -i https://app.nodea.io/api/v1/me \\ -H "Authorization: Bearer $NODEA\_TOKEN" \\ -H "X-Account-Id: 42" \\ -H "Accept: application/json" HTTP/2 200 X-Account-Id: 42 { "data": { "id": 7, "name": "Jan Kowalski", "email": "jan@example.com", "timezone": "Europe/Warsaw", "currency": "PLN", "default\_account\_id": 17, "current\_account": { "id": 42, "name": "Acme sp. z o.o.", "role": "member", "permissions": \["products", "domains", "tickets"\], "billing\_source": "whmcs", "is\_default": false, "is\_current": true }, "created\_at": "2025-03-01T10:00:00+00:00" } } ### Kody błędów - 401 — brak/niepoprawny token. - 403 — brak scope'a account:read (tylko /accounts) albo błąd kontekstu konta z tabeli poniżej. 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. 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" } ## MCP — kontekst konta Serwer MCP (/mcp) ustala bieżące konto tak samo jak API v1: konto przypiętego tokenu → nagłówek X-Account-Id **połączenia MCP** (ustaw go w konfiguracji klienta, obok nagłówka Authorization) → konto domyślne → jedyne członkostwo. Odpowiedzi HTTP niosą nagłówek X-Account-Id. Wszystkie narzędzia operujące na zasobach handlowych działają w tym jednym koncie; aby pracować w innym koncie, zmień nagłówek połączenia albo użyj tokenu przypiętego do tego konta. **Błędy połączenia.** Niepoprawne konto jest odrzucane na poziomie HTTP, zanim wykona się jakiekolwiek narzędzie: 403 z JSON {message, code} i kodem account\_forbidden (konto nie istnieje, jest obce, zamknięte lub usunięte) albo account\_mismatch (token przypięty do innego konta niż nagłówek). **Błędy narzędzi.** Odmowy wynikające z konta wracają jako wynik narzędzia z isError: true, a komunikat kończy się sufiksem maszynowym: - (code: account\_permission\_denied, permission: \) — brak uprawnienia konta; - (code: account\_owner\_required) — akcja tylko dla właściciela (hosting-terminate, server-delete serwera z VM); - (code: no\_account\_context) — nie udało się ustalić konta; - (code: termination\_locked) — globalna blokada terminacji; - (code: already\_terminated) — hosting-terminate na koncie już zterminowanym. Zasób spoza bieżącego konta zwraca dotychczasowy komunikat „… not found or not accessible with your permissions.” — identyczny jak dla zasobu nieistniejącego. Dostęp to scope tokenu ORAZ uprawnienie konta; właściciel ma wszystkie uprawnienia. ### Uprawnienia per grupa narzędzi Grupa narzędziUprawnienie kontaZgłoszenia: tickets-list, ticket-get, ticket-create, ticket-reply, ticket-closetickets Rozliczenia: billing-invoices, billing-invoice-get, billing-wallets, billing-transactions, billing-creditsinvoices; portfele, transakcje i darmowe kredyty dodatkowo wymagają konta rozliczanego przez Nodea (konto WHMCS → account\_permission\_denied, także dla właściciela) Domeny — odczyt: domains-list, domain-getdomains Domeny — akcje: domain-set-nameservers, domain-whois-privacy, domain-request-eppdomains + managedomains DNS — odczyt: dns-zones-list, dns-zone-getdomains DNS — rekordy: dns-record-create, dns-record-update, dns-record-deletedomains + managedomains Hosting — odczyt: hosting-list, hosting-get, hosting-emails, hosting-backupsproducts Hosting — akcje: hosting-email-create/-update/-delete, hosting-backup-create/-restore, hosting-issue-sslproducts + manageproducts Hosting — hosting-terminatetylko właściciel konta Serwery z maszyną wirtualną — odczytproducts Serwery z maszyną wirtualną — akcje (edycja, start/stop/reboot VM, WAF, komponenty, klon, test SSH, notatka)products + manageproducts Serwery z maszyną wirtualną — server-deletetylko właściciel konta Profil, monitoring, alerty, klucze SSH, Vault, serwery bez VMbrak — zasoby osobiste użytkownika ## MCP — narzędzia NarzędzieScopeTrybOpisaccounts-listaccount:readread-only, idempotentne**Nowe.** Bez argumentów. Zwraca {data: \[...\]} — wiersze jak w GET /api/v1/accounts (id, name, role, permissions\[\], billing\_source, is\_default, is\_current). Pomija konta zamknięte i usunięte; token przypięty widzi tylko swoje konto; najstarsze członkostwo pierwsze. whoami—read-onlyTożsamość (id, name, email, timezone), scopes tokenu oraz **nowe pola**: default\_account\_id, account (bieżące konto sesji lub null — wtedy narzędzia kont odpowiadają no\_account\_context) i accounts\[\] (konta, w których token może działać — te same wiersze co accounts-list). Pozostałe zmiany w narzędziach (zgłoszenia, rozliczenia, domeny, DNS, hosting, serwery, profile-update) są opisane we wpisach poszczególnych modułów. ### Przykład — MCP (JSON-RPC) { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "accounts-list", "arguments": {} } } { "jsonrpc": "2.0", "id": 1, "result": { "content": \[{ "type": "text", "text": "…" }\], "structuredContent": { "data": \[ { "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 }, { "id": 42, "name": "Acme sp. z o.o.", "role": "member", "permissions": \["products", "domains", "tickets"\], "billing\_source": "whmcs", "is\_default": false, "is\_current": false } \] } } } ### Jak sprawdzić, w którym koncie działa mój token? Wywołaj GET /api/v1/me — pole current\_account opisuje bieżące konto, a nagłówek odpowiedzi X-Account-Id zawiera jego identyfikator. W MCP to samo zwraca narzędzie whoami (pole account). ### Dlaczego dostaję 404 dla zasobu, który widzę w panelu? Zasób należy do innego konta niż bieżące konto żądania. Wyślij nagłówek X-Account-Id z identyfikatorem właściwego konta (lista w GET /api/v1/accounts) albo użyj tokenu przypiętego do tego konta. ### Co oznacza błąd account\_permission\_denied? Jesteś członkiem konta, ale właściciel nie nadał Ci uprawnienia wymaganego przez tę operację. Pole permission w odpowiedzi podaje nazwę brakującej flagi, np. managedomains. ## 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) - [Rozliczenia (billing) — API v1 i MCP | Dokumentacja Nodea](https://nodea.pl/pl/dokumentacja-api/billing) --- Wersje językowe: [en](https://nodea.io/en/api-docs/accounts.md) Spis treści witryny: [llms.txt](https://nodea.pl/pl/llms.txt)