Credentials (poświadczenia)

Klucz API wpisany prosto w pole węzła wygląda niewinnie. Działa od pierwszego kliknięcia. A potem eksportujesz workflow, żeby pokazać go koledze, wrzucasz zrzut ekranu na grupę albo kopiujesz plik do repozytorium - i klucz idzie razem z nim.

W analizie ponad 6 tysięcy publicznych workflow n8n klucze wpisane na sztywno w węzłach wyszły jako błąd numer jeden (źródło). Ta lekcja pokazuje, gdzie te klucze powinny siedzieć.

Czym są poświadczenia

Poświadczenia (credentials) to osobne miejsce w n8n na wszystko, co otwiera dostęp do usług: klucze API, tokeny, loginy i hasła, połączenia z kontem Google. Workflow nie przechowuje klucza. Przechowuje tylko odwołanie: „użyj poświadczenia o tej nazwie".

Co z tego masz:

• klucz nie wychodzi z eksportem - plik JSON workflow zawiera tylko nazwę i identyfikator poświadczenia, nigdy jego treść,
• klucz jest zaszyfrowany w bazie n8n,
• zmieniasz klucz w jednym miejscu - wszystkie workflow, które go używają, od razu biorą nowy,
• klucza nie widać na zrzutach ekranu - w węźle widnieje tylko nazwa poświadczenia.

Wszystkie swoje poświadczenia znajdziesz na stronie Overview, w zakładce Credentials.

Dwa rodzaje poświadczeń

Dedykowane - dla usług, które n8n obsługuje własnym węzłem: Google Sheets, Discord, Telegram, OpenAI i setki innych. Wybierasz typ, wklejasz klucz albo logujesz się przez okno usługi (OAuth) i gotowe.

Ogólne - do węzła HTTP Request, kiedy łączysz się z API, które nie ma własnego węzła. Najczęściej spotkasz trzy:

• Header Auth - klucz w nagłówku o wybranej nazwie, na przykład X-API-Key,
• Bearer Auth - token w nagłówku Authorization: Bearer .... Tak działa większość nowoczesnych API,
• Basic Auth - login i hasło.

Który wybrać, mówi dokumentacja API, z którym się łączysz. Szukasz w niej słowa „Authorization" albo „Authentication".

Zakładamy pierwsze poświadczenie

Ćwiczymy na httpbin.org - to publiczna usługa do testowania zapytań. Jej adres /bearer sprawdza, czy zapytanie ma token w nagłówku, i odsyła, co dostała. Żadnego konta nie potrzebujesz, a zobaczysz dokładnie, co n8n wysłał.

1. Wklej workflow z tej lekcji na pustą kanwę.
2. Otwórz węzeł Zapytanie z tokenem. Pole uwierzytelniania jest już ustawione na ogólne poświadczenie typu Bearer Auth, ale samego poświadczenia jeszcze nie ma.
3. W polu poświadczenia wybierz utworzenie nowego.
4. W polu Bearer Token wpisz dowolny tekst, na przykład moj-tajny-token-123.
5. Nadaj poświadczeniu nazwę, która powie ci za pół roku, do czego służy: „httpbin - token testowy".
6. Zapisz i kliknij Execute workflow.

W danych wyjściowych zobaczysz "authenticated": true i swój token. Usługa dostała go w nagłówku, a w samym węźle nie ma po nim śladu.

Teraz sprawdź eksport. Trzy kropki obok nazwy workflow, Export JSON, otwórz plik w edytorze. Znajdziesz w nim nazwę poświadczenia, ale nie token.

Pro-tip. Nazywaj poświadczenia według wzoru „usługa - konto - do czego". „Google - firma@ - arkusze raportów" mówi więcej niż „Google Sheets account 3", które n8n nada samo.

Ogranicz poświadczenie do jednej domeny

Poświadczenia ogólne mają pole Allowed HTTP Request Domains. Domyślnie jest ustawione na All, czyli wolno ich użyć z dowolną domeną. Przełącz na Specific Domains i wpisz tę jedną, dla której klucz jest przeznaczony, na przykład httpbin.org.

Po co? Jeśli ktoś, albo agent AI budujący workflow za ciebie, podepnie to poświadczenie pod zapytanie do innej domeny, n8n go nie wyśle. Twój klucz trafi tylko tam, gdzie powinien.

Zmienne środowiskowe to nie jest obejście

W starszych poradnikach zobaczysz klucze trzymane w zmiennych środowiskowych serwera i czytane w workflow przez $env. W n8n 2.x domyślnie to nie działa. Wyrażenie {{ $env.MOJ_KLUCZ }} i węzeł Code zwrócą błąd „access to env vars denied". Sprawdziłem na wersji 2.40.6.

Tak ma być. Klucze do usług trzymasz w poświadczeniach.

Haczyk. Poświadczenia są szyfrowane kluczem instancji. Na własnym serwerze albo w Dockerze ten klucz leży w katalogu danych n8n. Przenosisz n8n na inny serwer bez tego klucza - wszystkie poświadczenia są do wyrzucenia i zakładasz je od nowa. Jak go zabezpieczyć, pokazuję w dziale o n8n na serwerze.

Podsumowanie

Klucze, tokeny i hasła trzymasz w poświadczeniach, nigdy w polach węzłów. Workflow przechowuje tylko odwołanie, więc eksport i zrzuty ekranu są bezpieczne. Do API bez własnego węzła używasz poświadczeń ogólnych - najczęściej Bearer Auth albo Header Auth - i ograniczasz je do domeny, dla której są przeznaczone.

W lekcji 2.6 - Debugowanie i pin data zobaczysz, co zrobić, kiedy zapytanie się nie uda, i jak testować workflow, nie odpytując usługi przy każdym kliknięciu.

{
  "name": "Poswiadczenia - token w bezpiecznym miejscu",
  "nodes": [
    {
      "parameters": {},
      "type": "n8n-nodes-base.manualTrigger",
      "typeVersion": 1,
      "position": [
        0,
        0
      ],
      "id": "a5d1e001-0000-4000-8000-000000000001",
      "name": "Uruchom recznie"
    },
    {
      "parameters": {
        "url": "https://httpbin.org/bearer",
        "authentication": "genericCredentialType",
        "genericAuthType": "httpBearerAuth",
        "options": {}
      },
      "type": "n8n-nodes-base.httpRequest",
      "typeVersion": 4.4,
      "position": [
        220,
        0
      ],
      "id": "a5d1e001-0000-4000-8000-000000000002",
      "name": "Zapytanie z tokenem"
    }
  ],
  "connections": {
    "Uruchom recznie": {
      "main": [
        [
          {
            "node": "Zapytanie z tokenem",
            "type": "main",
            "index": 0
          }
        ]
      ]
    }
  },
  "settings": {
    "executionOrder": "v1"
  },
  "active": false
}