---
title: "Marka strony weryfikacji — API v1 i MCP | Dokumentacja Nodea"
description: "Reference modułu Marka strony weryfikacji antyDDoS: logo i ikona klienta per konto, serwer i domena, endpointy API v1, limity plików, sanityzacja SVG, stany dostarczenia, kody błędów i narzędzia MCP."
url: "https://nodea.pl/pl/dokumentacja-api/branding"
lang: "pl"
updated: "2026-11-18"
---

# Marka strony weryfikacji — API v1 i MCP | Dokumentacja Nodea

> Reference marki strony weryfikacji antyDDoS — logo i ikona per konto, serwer i domena; API v1, limity, kody błędów i narzędzia MCP.

Moduł **Marka strony weryfikacji** pozwala zastąpić logo Nodea na stronie weryfikacji antyDDoS (challenge) własnym logo i ikoną karty przeglądarki. Strona zostaje w białym motywie, a stopka „nodea.io · antyDDoS” jest zawsze widoczna. Markę ustawiasz na trzech poziomach: **konto**, **serwer** i **domena serwera**. Pierwszeństwo: `domena > serwer > konto > wygląd domyślny`. Dokument opisuje REST API v1 (`/api/v1/branding`, `/api/v1/servers/{server}/branding`) i narzędzia MCP modułu.

## Uwierzytelnianie, zakresy i flaga

Token osobisty Passport w nagłówku `Authorization: Bearer <token>`.

- `infra:read` — odczyt marki konta, serwera i domen.
- `infra:write` — zapis i usunięcie marki.

Moduł działa przy włączonych flagach `features:servers` i `features:challenge-branding`; wyłączona flaga daje `403`, a narzędzia MCP znikają z listy. Zapis wykonuje się od razu. **Usunięcie marki wymaga akceptacji człowieka**: odpowiedź `202` z `code: approval_required` i `data.approval_request` ([Akceptacje](https://nodea.pl/pl/dokumentacja-api/approvals), typ `branding.delete`) — po akceptacji w panelu Nodea wykonuje to samo żądanie. Usunięta marka znika z serwerów, a nieużywany obraz jest kasowany po 7 dniach.

## Uprawnienia

- **Konto** — bieżące konto tokenu (`X-Account-Id`): odczyt wymaga uprawnienia `products`, zapis i usunięcie — `products` i `manageproducts` (`403 account_permission_denied`).
- **Serwer i domeny** — odczyt: członek konta VM z `products`, właściciel serwera spoza konta albo członek konta serwera dedykowanego, którego serwer jest hostem. Udostępniony podgląd monitoringu (wiersz „obcy”) nie widzi marki. Zapis i usunięcie: zarządzanie serwerem (VM — `manageproducts`) albo serwerem dedykowanym. Serwer VM innego konta niż bieżące konto tokenu — zapis daje `403`, serwer niewidoczny — `404`. Serwer hostingowy Nodea (host operatora) — tylko odczyt, zapis daje `403` z `code: operator_host`.
- Marka konta trafia na serwery konta (VM i serwery dedykowane), które nie mają własnej marki serwera. Serwer spoza konta nie dziedziczy marki konta.
- Zmiana konta serwera (cesja, przeniesienie usługi) usuwa marki serwera i jego domen ustawione przez poprzedniego klienta; serwer dziedziczy markę nowego konta.

## Pliki i limity

| Pole | Formaty | Limit |
| --- | --- | --- |
| `logo` | SVG, PNG, WebP (bez animacji) | SVG ≤ 32 kB po sanityzacji; PNG/WebP ≤ 64 kB i ≤ 512 px w każdym wymiarze. |
| `favicon` | PNG, WebP, ICO (także ICO z wpisem PNG) | ≤ 16 kB, każdy wpis ICO ≤ 512 px; zapisywana zawsze jako PNG zmieszczony w 64 × 64 px. |
| `alt` | tekst | wymagany, ≤ 120 znaków po normalizacji (bez znaków sterujących, NFC); wyświetlany zawsze jako zwykły tekst. |

Typ pliku rozpoznajemy z treści, nie z nazwy. SVG jest czyszczony: znikają skrypty, obsługa zdarzeń (`on*`), atrybut `style`, `<style>`, `<foreignObject>`, osadzone obrazy, odnośniki, animacje, `<title>`, `<desc>`, komentarze oraz `href` i `url()` spoza pliku. Proste reguły klas z `<style>` zamieniamy na atrybuty, żeby kolory zostały. `url('#id')` i `url( #id )` normalizujemy do `url(#id)`. `<use>` zostaje najwyżej 64 razy i tylko wtedy, gdy wskazuje istniejący element, który nie zawiera `<use>` i nie jest jego przodkiem. Znaki `\` i `javascript:` w tekście `<text>` są neutralizowane. Plik z `DOCTYPE`, encjami albo instrukcjami przetwarzania jest odrzucany. Rastry kodujemy ponownie bez metadanych. Bez wgranej ikony panel generuje ją z logo (PNG, WebP i SVG) jako PNG 64 × 64 px — `favicon_generated: true`.

## API v1 — endpointy

| Metoda | Ścieżka | Scope | Opis |
| --- | --- | --- | --- |
| GET | /api/v1/branding | infra:read | Marka bieżącego konta: `{account_id, brand, affected_servers, delivery_summary}`. |
| POST/PUT | /api/v1/branding | infra:write | Zapis marki konta. Zwraca `{data: {brand}, warnings[]}`. |
| DELETE | /api/v1/branding | infra:write | **Wymaga akceptacji człowieka** (`202 approval_required`). Po akceptacji: usunięcie marki konta, `204`. Brak marki — `404`. |
| GET | /api/v1/servers/{server}/branding | infra:read | Marka własna serwera, marka efektywna ze źródłem, stan dostarczenia do agenta i marki domen. |
| POST/PUT | /api/v1/servers/{server}/branding | infra:write | Zapis marki serwera. Zwraca `{data: {brand}, warnings[]}`. |
| DELETE | /api/v1/servers/{server}/branding | infra:write | **Wymaga akceptacji człowieka** (`202 approval_required`). Po akceptacji: usunięcie marki serwera (serwer wraca do marki konta), `204`. Brak marki — `404`. |
| GET | /api/v1/servers/{server}/branding/domains/{host} | infra:read | Marka jednej domeny serwera ze stanem dostarczenia (kształt elementu `domains[]` + `server_id`). Brak marki — `404`. |
| POST/PUT | /api/v1/servers/{server}/branding/domains/{host} | infra:write | Zapis marki jednej domeny serwera (do 200 domen na serwer). Zwraca `{data: {brand}, warnings[]}`. |
| DELETE | /api/v1/servers/{server}/branding/domains/{host} | infra:write | **Wymaga akceptacji człowieka** (`202 approval_required`). Po akceptacji: usunięcie marki domeny, `204`. Brak marki — `404`. |

### Ciało zapisu

- `multipart/form-data` (metoda POST): `logo` (plik), `favicon` (plik, opcjonalnie), `remove_favicon` (bool), `alt`.
- JSON (POST albo PUT): `logo_base64`, `favicon_base64` (base64, dozwolony prefiks `data:…;base64,`), `remove_favicon`, `alt`.
- Pominięte logo = zostaje obecne (przy pierwszym zapisie wymagane). Pominięta ikona = zostaje wgrana albo panel generuje ją z logo; `remove_favicon: true` usuwa wgraną ikonę.
- `{host}` przyjmujemy także z portem i w Unicode i normalizujemy: małe litery, punycode, bez `www.`, portu i kropki na końcu. Ścieżka, schemat albo nieprawidłowa nazwa — `422 invalid_host`.

### Odpowiedź `GET /api/v1/branding`

- `account_id` — id konta; `brand` — obiekt `brand` albo `null`.
- `affected_servers` — **liczba** serwerów konta, które dziedziczą markę konta (bez własnej marki serwera).
- `delivery_summary` — liczby serwerów dziedziczących wg stanu: `applied`, `pending` (czeka na wysłanie albo wysłana i czeka na potwierdzenie), `rejected`, `unsupported` (agent bez obsługi marki), `no_agent` (serwer bez agenta nodeaD). Suma = `affected_servers`, gdy konto ma markę; bez marki wszystkie wartości to `0`.

### Odpowiedź `GET /api/v1/servers/{server}/branding`

- `server_id`; `own` — własna marka serwera (`brand` albo `null`).
- `effective` — `{source, brand}`: marka, którą widzą odwiedzający domeny bez własnej marki; `source`: `server`, `account` albo `default` (wtedy `brand: null`).
- `delivery` — stan dostarczenia `brand/serwer` do agenta (obiekt `delivery`).
- `domains[]` — marki domen posortowane po nazwie: `{host, hash, alt, logo, favicon, favicon_generated, updated_at, delivery}`.

### Obiekt `brand`

`uuid`, `scope` (`account|server|domain`), `host` (tylko domena), `logo` i `favicon` (`{sha256, mime, bytes, width, height}` albo `null`), `favicon_generated` (ikona wygenerowana przez panel z logo), `alt`, `hash` (wersja marki, 64 znaki hex), `updated_at` (ISO 8601).

### Obiekt `delivery`

- `state`: `applied` — działa na serwerze; `sent` — wysłana, czeka na potwierdzenie; `pending` — czeka na wysłanie; `rejected` — odrzucona przez serwer; `unsupported` — agent nodeaD nie obsługuje marki (zaktualizuj nodeaD); `no_agent` — serwer bez agenta; `not_applicable` — wygląd domyślny, nic do dostarczenia.
- `reason` — opis stanu do wyświetlenia (w języku żądania) albo `null`.
- `reason_code` — stabilny kod: `no_agent`, `unsupported` albo kod odrzucenia przez serwer: `nieznany_typ`, `walidacja`, `za_duzy`, `format`, `poza_zakresem`, `rev_z_przyszlosci`, `nieprawidlowy_payload`, `pobierz_nieobslugiwane`, `konflikt`, `blad_wewnetrzny`; nieznany kod agenta — `inny`. Dla pozostałych stanów `null`.
- `reason_detail` — szczegół od agenta (wolny tekst, nie tłumaczony) albo `null`.
- `delivered_at` — chwila potwierdzenia przez serwer (ISO 8601) albo `null`.

Zmiany trafiają tylko do serwerów, których dotyczą, zwykle w ciągu kilku sekund. Panel co godzinę porównuje stan docelowy z serwerami i ponawia zaległe wysyłki.

### Ostrzeżenia zapisu (`warnings[]`)

- Marka serwera i domeny: `{code, message}`, `code`: `no_agent` albo `agent_unsupported`.
- Marka konta: `{code, count, message}` — `count` serwerów dziedziczących z `agent_unsupported` albo `no_agent`.
- Marka jest zapisana i trafi na serwer, gdy pojawi się agent z obsługą marki.

### Kody błędów

| Status | `code` | Kiedy |
| --- | --- | --- |
| 422 | `image_too_large` | Plik przekracza limit (po sanityzacji albo ponownym zakodowaniu). |
| 422 | `image_dimensions` | Raster albo wpis ICO większy niż 512 px. |
| 422 | `image_unsupported` | Format spoza listy albo animacja. |
| 422 | `svg_rejected` | SVG z `DOCTYPE`, encjami, bez wymiarów, za duży lub za głęboki. |
| 422 | `invalid_base64` | Niepoprawne base64 w `logo_base64` albo `favicon_base64`. |
| 422 | `invalid_host` | Nieprawidłowa nazwa domeny. |
| 422 | `logo_required` | Pierwszy zapis bez logo. |
| 422 | `too_many_domains` | Serwer ma już 200 marek domen. |
| 202 | `approval_required` | Usunięcie marki czeka na akceptację człowieka. |
| 403 | `operator_host`, `account_permission_denied` | Serwer hostingowy Nodea albo brak uprawnienia w koncie. |
| 404 | — | Serwer niewidoczny dla tokenu albo brak marki na tym poziomie (konto, serwer, domena). |
| 429 | — | Ponad 30 zapisów i usunięć na minutę. |

Błąd 422 ma kształt walidacji: `{message, code, errors: {pole: [komunikat]}}`.

### Przykład

**REST API · curl**

```bash
curl -X POST https://app.nodea.io/api/v1/servers/SERVER_ID/branding \
  -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" \
  -F logo=@logo.svg -F alt="Sklep Kowalski"
```

## Narzędzia MCP

| Narzędzie | Scope | Parametry | Wynik |
| --- | --- | --- | --- |
| branding-get | infra:read | `scope` (`account\|server\|domain`), `server`?, `host`? | Pole `scope` i dane jak w API: `account` — jak `GET /api/v1/branding`; `server` — jak `GET /api/v1/servers/{server}/branding`; `domain` — `{server_id, brand}`, gdzie `brand` ma kształt elementu `domains[]` albo `null`. |
| branding-set | infra:write | `scope`, `server`?, `host`?, `logo_base64`?, `favicon_base64`?, `remove_favicon`?, `alt` | `{saved, brand, warnings}`; błąd jako tekst `<code>: <komunikat>` z kodami jak w API (także `invalid_base64`, `operator_host`). |
| branding-delete | infra:write | `scope`, `server`?, `host`? | **Wymaga akceptacji człowieka**: `{code: approval_required, approval_request}`; po akceptacji `{deleted, scope}`. Brak marki — błąd `not_found`. |

## Powiązane

- [Serwery — API v1 i MCP | Dokumentacja Nodea](https://nodea.pl/pl/dokumentacja-api/servers)
- [Serwer MCP Nodea — endpoint, uwierzytelnianie, discovery OAuth, narzędzia | Nodea](https://nodea.pl/pl/dokumentacja-api/mcp)
- [API Nodea v1 — wprowadzenie: base URL, tokeny, scope'y, limity | Nodea](https://nodea.pl/pl/dokumentacja-api/overview)

---

Wersje językowe: [en](https://nodea.io/en/api-docs/branding.md)  
Spis treści witryny: [llms.txt](https://nodea.pl/pl/llms.txt)
