API kľúče a premenné prostredia

Pripojenie je takmer hotové. Agent zostavil konfiguráciu, pomenoval službu a zastavil sa na jednom poli - API key. Služba vydala dlhý reťazec a z neho samotného nie je jasné, kam ho dať. Do konverzácie? Do súboru vedľa kódu? Priamo do konfigurácie, aby to určite fungovalo?

Pozrieme sa na to na jednom modeli. Uvidíme, kde sa hodnota nastavuje, ktorý proces ju dostane a ako si overiť, že je všetko nastavené, a pritom neukázať samotné tajomstvo. Model je rovnaký pre lokálne spustenie, pre pripojenie MCP aj pre publikovanú aplikáciu - mení sa len to, čie prostredie nastavujeme.

Čo dáva prístupový kľúč

Kľúč prepája požiadavku s účtom alebo projektom a s právami, ktoré ste dostali. Podľa neho služba zistí, kto sa na ňu obrátil, čo tento volajúci smie a koľko toho už vyžiadal. Presný zmysel kľúča určuje konkrétna služba. Niekde ide o prístup k celému účtu, niekde len k jednému projektu a len na čítanie.

V návodoch sa vedľa slova "kľúč" objavuje aj token. V bežných textoch sa často používajú ako to isté, ale detaily mechanizmu sa líšia. Ide o spôsob získania, dobu platnosti a rozsah práv. Za úplné synonymá ich radšej nepovažujte - čo presne služba vydáva, je napísané v jej dokumentácii.

Prečo vás služba vôbec potrebuje rozlišovať, najľahšie ukáže bežný príklad. Vytvorili ste účet, vybrali ste si tarif s mesačným limitom požiadaviek a dostali ste kľúč. Ďalej služba podľa tohto kľúča počíta vaše požiadavky, porovnáva ich s limitom a ak je tarif platený, vystavuje faktúru. Kľúč, ktorý sa dostal k cudzím osobám, znamená, že limit a faktúra idú niekomu inému.

Kľúč sám nič nerozhoduje. Poskytuje službe odkaz na nastavenia vlastníka a až služba rozhodne, či je konkrétna požiadavka povolená a či ju treba odpočítať z limitu.

Existujú aj hodnoty, ktoré služba výslovne označuje ako verejné - tie treba umiestniť do kódu stránky. Verejnú hodnotu nerozlíšite od tajnej podľa názvu premennej. Účel je napísaný v dokumentácii, pozerať treba tam. V príkladoch nižšie sú všade zjavné zástupné hodnoty ako fc-EXAMPLE-0000000000, skutočný kľúč tak nevyzerá.

Kde môže aplikácia uložiť tajomstvo

Predstavte si takúto situáciu. Pridali ste kľúč priamo do kódu stránky, spustili ste projekt a dostali ste odpoveď od API. Všetko funguje. Aj po publikácii sa aplikácia otvára, požiadavky prechádzajú - zdá sa, že úloha je vyriešená.

Lenže spolu s kódom dostane kľúč aj prehliadač každého návštevníka. Stačí otvoriť vývojárske nástroje, nájsť ho v JavaScripte alebo v požiadavke a skopírovať. Potom môže ten človek posielať vlastné požiadavky vo vašom mene. Budú míňať váš limit, až kým služba nezačne odmietať už vaše požiadavky.

Problém nie je v konkrétnom nástroji na build. Všetko, čo stránka poslala prehliadaču, má k dispozícii jeho vlastník: HTML, štýly, JavaScript, adresy a hlavičky požiadaviek. Aj keď sa kľúč počas buildu vzal z lokálneho .env, po dosadení do JavaScriptu odišiel k návštevníkovi spolu so zvyškom kódu.

Backend je kód, ktorý beží na serveri. Návštevník dostáva jeho odpovede, ale nie zdrojový kód ani premenné prostredia serverového procesu. Preto môže backend držať kľúč u seba a obracať sa na externú službu v mene aplikácie.

Schéma požiadavky sa zmení. Prehliadač pošle vášmu backendu bežnú požiadavku bez tajného kľúča. Backend načíta kľúč zo svojho prostredia, pridá ho do samostatnej požiadavky na API a prehliadaču vráti len výsledok.

Teraz návštevník vidí adresu backendu a údaje z odpovede, ale nie kľúč externej služby. Tajomstvo zostáva pri procese, ktorý ho používa.

Tajomstvo má dvoch možných vlastníkov:

• lokálny proces - Claude Code s pripojenou integráciou, skript alebo dev-server. Spúšťa sa na vašom počítači a tam aj dostáva kľúč;
• backend publikovanej aplikácie - kód na serveri, ktorý sa sám obracia na externé API. Jeho prostredie sa nastavuje v paneli hostingu.

Sú to dve samostatné nastavenia. Kľúč z prostredia vášho počítača sa na hostingu sám neobjaví, aj keď sa služba aj názov premennej zhodujú.

Presun kľúča na backend ho skryje pred prehliadačom, ale verejný backend treba aj tak chrániť pred cudzími požiadavkami.

Ako funguje premenná prostredia

Premenná prostredia je pomenovaná hodnota, ktorú program dostane pri spustení. Má názov, napríklad FIRECRAWL_API_KEY, a hodnotu, ten dlhý reťazec. Do konfigurácií a do kódu sa píše názov; hodnota žije oddelene a vedľa kódu sa neukladá.

Odkiaľ ju program berie? Program spustený z terminálu dedí prostredie tohto terminálu. Nastavili ste premennú v okne, spustili ste z neho Claude Code - Claude Code ju vidí. Otvorili ste druhé okno a nastavili premennú tam - na už bežiaci proces to nemá vplyv, prostredie dostal pri štarte.

Odtiaľ pochádza najčastejšia sťažnosť "kľúč predsa je nastavený, a nefunguje". Hodnota je nastavená v inom okne alebo až po spustení. Rieši sa to reštartom procesu z terminálu, v ktorom premenná je.

Cvičná verzia so zjavne fiktívnou hodnotou:

# bash: premenná pre aktuálny terminál
export FIRECRAWL_API_KEY=fc-EXAMPLE-0000000000

# PowerShell: to isté
$env:FIRECRAWL_API_KEY = "fc-EXAMPLE-0000000000"

So zástupnou hodnotou v cvičnom príklade sa to takto písať dá. Skutočný kľúč takto zadávať nie je dobrý nápad. Celý riadok sa uloží do histórie príkazov a zostane tam aj po zatvorení terminálu. Pre skutočnú hodnotu existuje zadávanie bez ozveny - reťazec vložíte, na obrazovke sa nič neobjaví a do histórie sa dostane len samotný príkaz:

# bash: hodnota sa zadáva skryto
read -s -r FIRECRAWL_API_KEY
export FIRECRAWL_API_KEY

# PowerShell: skrytý vstup a rozbalenie hodnoty do premennej prostredia
$secure = Read-Host "FIRECRAWL_API_KEY" -AsSecureString
$env:FIRECRAWL_API_KEY = [System.Net.NetworkCredential]::new('', $secure).Password

Nastavenie treba kontrolovať tak, aby sa hodnota neobjavila na obrazovke, v logu ani na snímke obrazovky. Na otázku "je to nastavené, alebo nie" stačia dva riadky:

# bash
[ -n "$FIRECRAWL_API_KEY" ] && echo "nastavené" || echo "nie je nastavené"

# PowerShell
if ($env:FIRECRAWL_API_KEY) { "nastavené" } else { "nie je nastavené" }

Nevypisujte ani dĺžku, ani prvé znaky. Kontrole to nič nepridá a úryvok kľúča je už časť tajomstva.

Spôsobov, ako nastaviť premennú natrvalo, je veľa a každý systém má vlastné. Teraz sa v nich vyznať nemusíte: na lokálnu prácu stačí terminál a na hostingu sa premenné nastavujú v jeho vlastnom paneli.

Na čo sú .env a .env.example

Ručné nastavovanie premenných v každom novom termináli rýchlo omrzí, preto sa hodnoty ukladajú do textového súboru .env. Jeden riadok v ňom obsahuje jednu dvojicu názov a hodnota.

Najčastejšie sa prehliadne dôležitý detail. Samotný súbor nič nenastavuje. Niekto ho musí prečítať a rozložiť hodnoty do prostredia procesu - aplikácia, knižnica alebo launcher, ktorý spúšťa váš program. Vytvoriť .env a počítať s tým, že ho odteraz načíta akýkoľvek program, nemôžete. Čo presne súbor vo vašom prípade načítava, treba zistiť priamo, nie predpokladať.

Vedľa neho zvyčajne ležia ešte dva súbory:

# .env - zostáva len na vašom počítači
FIRECRAWL_API_KEY=fc-EXAMPLE-0000000000

# .env.example - šablóna pre tých, ktorí otvoria projekt
# hodnoty sú prázdne, sú tu len názvy
FIRECRAWL_API_KEY=

# .gitignore
.env

Zmysel rozdelenia je jednoduchý. .env.example odpovedá na otázku "aké premenné sú potrebné tomuto projektu" a pokojne môže byť v repozitári, pretože v ňom nie sú žiadne hodnoty. Skutočné kľúče sa doň neprenášajú ani dočasne.

Ak Git ešte nepoznáte, tu si stačí zapamätať úlohu .gitignore. Vymenúva súbory, ktoré sa nemajú pridávať do repozitára. Prácu s Gitom a .gitignore podrobne rozoberieme na úrovni 13.

A teraz pasca s .gitignore, do ktorej sa padá pravidelne. Pravidlo platí len pre súbory, ktoré Git ešte nesleduje. Ak ste .env niekedy commitli, pridanie riadku do .gitignore ho neodpojí. Súbor zostane pod správou verzií a jeho zmeny sa budú naďalej dostávať do commitov. Dokumentácia Gitu to hovorí priamo. Súbory, ktoré Git už sleduje, nie sú ovplyvnené pravidlami ignorovania. Dokumentácia gitignore.

Hlavná podmienka je na schéme v strede. Ten istý riadok v .gitignore pomáha, len kým .env nie je sledovaný. Pre už sledovaný súbor treba samostatný krok.

Preto sa skôr, než do súboru zapíšete skutočné tajomstvo, oplatí overiť, že oň Git nevie. git status ukáže, či sa súbor dostáva medzi zmeny. Ak je súbor už sledovaný, zo sledovania sa odstráni príkazom git rm --cached .env a táto zmena sa commitne - súbor zostane na disku, ale vypadne zo správy verzií.

Len majte na pamäti, že to ovplyvní budúce commity. Hodnota, ktorá sa už dostala do histórie, tam zostane a treba s ňou naložiť inak - o tom nižšie.

Ako odovzdať kľúč pripojeniu MCP

MCP je spôsob, ako pripojiť externý nástroj ku Claude Code. Pripojenie sa opisuje v súbore .mcp.json a tento súbor zvyčajne leží v repozitári spolu s projektom, čiže ho vidí celý tím. Tajomstvo v ňom teda byť nemá.

Minimálne pripojenie služby Firecrawl cez HTTP vyzerá takto:

{
  "mcpServers": {
    "firecrawl": {
      "type": "http",
      "url": "https://mcp.firecrawl.dev/v2/mcp",
      "headers": {
        "Authorization": "Bearer ${FIRECRAWL_API_KEY}"
      }
    }
  }
}

Kľúč v súbore nie je. V hlavičke je ${FIRECRAWL_API_KEY} - odkaz na premennú prostredia podľa názvu. Claude Code sem dosadí hodnotu z prostredia procesu, v ktorom beží. Do repozitára ide názov, hodnotu má každý svoju. Takéto dosadenie Claude Code vie urobiť v poliach url, headers, env, command a args. Claude Code o MCP.

Na schéme vidno, že v hlavičke požiadavky sa stretávajú dve veci z rôznych miest. Šablóna hlavičky prichádza zo spoločnej konfigurácie a hodnota sa dosadí z prostredia procesu. V žiadnom kroku sa kľúč nezapíše do súboru, ktorý ide do repozitára.

Adresu a spôsob odovzdania kľúča berte z dokumentácie samotnej služby. Pri Firecrawl je to hlavička Authorization a dokumentácia osobitne žiada nedávať kľúč do MCP adresy. Dôvod je jednoduchý. Adresa je obyčajný text, dostane sa do konfigurácie, do logov a do histórie príkazov a spolu s ňou sa tam dostane aj kľúč.

Niektoré služby podporujú prihlásenie cez prehliadač. Klient sám otvorí prihlasovaciu stránku a API key ručne odovzdávať vôbec netreba. Firecrawl má na to samostatnú adresu. Dokumentácia Firecrawl o MCP.

Ak nástroj neodpovedá, kontrolujte v tomto poradí:

1. názov premennej v konfigurácii a názov, ktorý ste nastavili, sa zhodujú do posledného znaku;
2. hodnota je nastavená v procese, z ktorého je spustený Claude Code;
3. proces sa reštartoval po nastavení premennej.

Keď premenná chýba, Claude Code potichu nespadne. Načíta konfiguráciu, text ${FIRECRAWL_API_KEY} nechá nedosadený a vypíše varovanie s názvom chýbajúcej premennej. Samotná hodnota sa pritom nikde nevypisuje, takže diagnostika je bezpečná. Vypisovať celé prostredie, aby ste našli problém, určite netreba.

Ak sa kľúč už dostal von

Situácia je bežná. Kľúč sa ocitol v správe, v commite alebo na snímke obrazovky. Panikáriť netreba, ale odkladať to tiež nie. Postup je takýto:

1. odvolať alebo vymeniť kľúč v administrácii služby. Je to jediný krok, po ktorom starý reťazec prestane čokoľvek otvárať;
2. nastaviť novú hodnotu tam, kde je potrebná: lokálne, na hostingu, v nastaveniach pripojenia;
3. vyriešiť miesto, kde kľúč unikol - vymazať správu, opraviť súbor, zrušiť prístup;
4. pozrieť sa v administrácii, ako sa kľúč používal a čo služba ukazuje vo výdavkoch.

Poradie je presne takéto a prvý krok sa nepresúva. Vymazaná správa ani nový commit nad starým neurobia z niekdajšieho tajomstva bezpečnú vec. Správu si mohli prečítať, repozitár naklonovať, históriu uložiť. Kým kľúč platí, platí u každého, kto ho má.

K repozitáru zvlášť. Ak sa tajomstvo dostalo do commitu, GitHub má návod na odstránenie takých údajov. Odstránenie citlivých údajov z repozitára. Len majte na pamäti, že úplné vyčistenie histórie prepíše už existujúce commity, a teda zasiahne všetkých, ktorí s týmto repozitárom pracujú. Takú operáciu treba dohodnúť s vlastníkmi, nie spustiť ju na vlastnú päsť podľa výukového článku. Výmena kľúča sa robí hneď a s nikým sa nedohaduje.

Čo zveriť Claude Code

Agent zvládne takmer celú mechaniku z tohto článku, okrem jednej veci. Samotné tajomstvo zadávate vy. Rozumné je zveriť mu toto:

• pripraviť konfiguráciu s názvom premennej, nie s hodnotou;
• povedať, čo presne načítava premennú do procesu a v ktorom procese sa má ocitnúť;
• skontrolovať, že tajomstvo nie je v klientskom builde ani v súboroch, ktoré sleduje Git;
• vykonať kontrolu prístupu a oznámiť výsledok bez vypísania hodnoty.

Na vás zostáva zadanie skutočného kľúča cez mechanizmus, ktorý je na to určený: skryté zadanie v termináli, lokálny súbor, panel hostingu. Do konverzácie, na snímku obrazovky ani do správy agenta sa tajomstvo nedostane nikdy, ani "na sekundu, len na skúšku".

Zadanie môže znieť približne takto:

Pripoj službu cez API. Kľúč nastavím sám.
Vezmi z dokumentácie adresu, metódu a spôsob odovzdania kľúča.
Do konfigurácie daj názov premennej prostredia, nie hodnotu.
Povedz, ktorý proces má dostať premennú a čo ju načítava.
Skontroluj, že kľúč nie je v klientskom builde ani v súboroch, ktoré sleduje Git.
Kontrolu prístupu urob bez vypísania hodnoty a jej častí.
Oznám výsledok: nastavené, nenastavené alebo prístup zamietnutý.

A nakoniec k čítaniu správy. "Premenná je nastavená" a "prístup funguje" sú rôzne tvrdenia a zamieňať jedno za druhé nemá zmysel. Chýbajúca hodnota sa tiež líši od odmietnutia zo strany služby. V prvom prípade nie je čím požiadavku podpísať, v druhom služba odpovedala, ale prístup nepovolila. Ak agent povie len "hotovo", spýtajte sa, čo presne skontroloval.