Chei API și variabile de mediu

Conexiunea este aproape gata. Agentul a pregătit configurația, a numit serviciul și s-a oprit la un singur câmp - API key. Serviciul v-a dat un șir lung de caractere, iar din el însuși nu reiese unde trebuie pus. În chat? Într-un fișier lângă cod? Direct în configurație, ca să meargă sigur?

Să lămurim asta pe un singur model. Vom vedea unde se setează valoarea, ce proces o primește și cum vă asigurați că totul e configurat, fără a afișa secretul în sine. Modelul este același pentru rularea locală, pentru conexiunea MCP și pentru aplicația publicată - se schimbă doar procesul al cărui mediu îl configurăm.

Ce oferă cheia de acces

Cheia leagă cererea de un cont sau proiect și cu drepturile care v-au fost acordate. După ea, serviciul înțelege cine a trimis cererea, ce are voie să facă și cât a consumat deja. Semnificația exactă a cheii o stabilește fiecare serviciu. Undeva înseamnă acces la întregul cont, altundeva doar la un singur proiect și doar pentru citire.

Lângă cuvântul "cheie", în instrucțiuni apare și token. În textele de zi cu zi cele două sunt adesea folosite ca același lucru, dar detaliile mecanismului diferă: modul de obținere, perioada de valabilitate și setul de drepturi. Mai bine nu le considerați sinonime complete - ce anume emite serviciul scrie în documentația lui.

De ce are nevoie serviciul să vă deosebească de alții se vede mai ușor pe un exemplu din viața de zi cu zi. V-ați creat un cont, ați ales un plan tarifar cu o limită lunară de cereri și ați primit o cheie. Mai departe, serviciul numără cererile dumneavoastră după această cheie, le compară cu limita și, dacă planul este plătit, emite factura. O cheie ajunsă pe mâini străine înseamnă că limita și factura ajung să fie ale altcuiva.

Cheia nu ia singură decizia. Ea îi indică serviciului setările proprietarului, iar serviciul decide dacă o anumită cerere este permisă și dacă trebuie scăzută din limită.

Există și valori pe care serviciul le marchează anume ca publice - pe acestea chiar trebuie să le puneți în codul paginii. După numele variabilei nu puteți deosebi o valoare publică de una secretă. Destinația ei este descrisă în documentație, acolo trebuie să vă uitați. În exemplele de mai jos apar peste tot înlocuitori evidenți, de tipul fc-EXAMPLE-0000000000; o cheie reală nu arată așa.

Unde poate o aplicație să stocheze secretul

Imaginați-vă următoarea situație. Ați pus cheia direct în codul paginii, ați pornit proiectul și ați primit răspuns de la API. Totul funcționează. După publicare aplicația se deschide și ea, cererile trec - pare că problema e rezolvată.

Dar odată cu codul, browserul fiecărui vizitator primește și cheia. E suficient să deschidă instrumentele pentru dezvoltatori, s-o găsească în JavaScript sau în cerere și s-o copieze. Din acel moment, omul poate trimite propriile cereri în numele dumneavoastră. Ele vor consuma limita dumneavoastră, până când serviciul va începe să vă respingă chiar cererile dumneavoastră.

Problema nu ține de un anumit instrument de build. Tot ce pagina a trimis browserului este la îndemâna proprietarului acestuia: HTML, stiluri, JavaScript, adresele și antetele cererilor. Chiar dacă la build cheia a fost luată din fișierul local .env, după ce a fost inserată în JavaScript a plecat la vizitator odată cu restul codului.

Backend este codul care rulează pe server. Vizitatorul primește răspunsurile lui, dar nu și codul sursă sau variabilele de mediu ale procesului de pe server. De aceea backend-ul poate păstra cheia la el și poate apela serviciul extern în numele aplicației.

Schema cererii se schimbă. Browserul trimite backend-ului dumneavoastră o cerere obișnuită, fără cheia secretă. Backend-ul citește cheia din propriul mediu, o adaugă într-o cerere separată către API și îi întoarce browserului doar rezultatul.

Acum vizitatorul vede adresa backend-ului și datele din răspuns, dar nu și cheia serviciului extern. Secretul rămâne la procesul care îl folosește.

Secretul are doi posibili proprietari:

• procesul local - Claude Code cu o integrare conectată, un script sau un server de dezvoltare. Rulează pe computerul dumneavoastră și primește cheia tot acolo;
• backend-ul aplicației publicate - codul de pe server care apelează singur API-ul extern. Mediul lui se configurează în panoul hostingului.

Acestea sunt două configurări separate. Cheia din mediul computerului dumneavoastră nu va apărea de la sine pe hosting, chiar dacă serviciul și numele variabilei coincid.

Mutarea cheii pe backend o ascunde de browser, dar un backend public trebuie totuși protejat de cererile străine.

Cum funcționează variabila de mediu

Variabila de mediu este o valoare numită pe care o primește programul la pornire. Are un nume, de exemplu FIRECRAWL_API_KEY, și o valoare - chiar acel șir lung. În configurații și în cod se scrie numele; valoarea trăiește separat și nu se păstrează lângă cod.

De unde o ia programul. Un program pornit din terminal moștenește mediul acelui terminal. Ați setat variabila într-o fereastră și ați pornit Claude Code din ea - Claude Code o vede. Ați deschis a doua fereastră și ați setat variabila acolo - asupra procesului care rulează deja nu are niciun efect, el și-a primit mediul la pornire.

De aici vine cea mai frecventă plângere: "cheia e setată, dar nu merge". Valoarea a fost setată în altă fereastră sau după pornire. Se rezolvă repornind procesul din terminalul în care există variabila.

Varianta de învățare, cu o valoare clar fictivă:

# bash: variabilă pentru terminalul curent
export FIRECRAWL_API_KEY=fc-EXAMPLE-0000000000

# PowerShell: același lucru
$env:FIRECRAWL_API_KEY = "fc-EXAMPLE-0000000000"

Cu un înlocuitor, într-un exemplu didactic, se poate scrie așa. O cheie reală însă nu merită tastată în acest mod. Întreaga linie ajunge în istoricul comenzilor și rămâne acolo și după ce închideți terminalul. Pentru valoarea reală există introducerea fără ecou - lipiți șirul, pe ecran nu apare nimic, iar în istoric ajunge doar comanda în sine:

# bash: valoarea este introdusă ascuns
read -s -r FIRECRAWL_API_KEY
export FIRECRAWL_API_KEY

# PowerShell: intrare ascunsă și despachetarea valorii în variabila de mediu
$secure = Read-Host "FIRECRAWL_API_KEY" -AsSecureString
$env:FIRECRAWL_API_KEY = [System.Net.NetworkCredential]::new('', $secure).Password

Configurarea trebuie verificată astfel încât valoarea să nu apară pe ecran, în jurnal sau într-o captură de ecran. Pentru întrebarea "e setată sau nu" ajung două linii:

# bash
[ -n "$FIRECRAWL_API_KEY" ] && echo "setat" || echo "nu este setat"

# PowerShell
if ($env:FIRECRAWL_API_KEY) { "setat" } else { "nu este setat" }

Nu afișați nici lungimea, nici primele caractere. Verificării nu-i adaugă nimic, iar un fragment din cheie este deja o parte din secret.

Moduri de a seta o variabilă permanent sunt multe, și fiecare sistem le are pe ale lui. Nu e nevoie să vă ocupați de ele acum: pentru lucrul local ajunge terminalul, iar pe hosting variabilele se setează în panoul acestuia.

De ce sunt necesare .env și .env.example

Să setați variabilele de mână în fiecare terminal nou devine repede obositor, așa că valorile se pun într-un fișier text .env. O linie din el păstrează o pereche nume-valoare.

Cel mai des scapă din vedere un detaliu important. Fișierul în sine nu configurează nimic. Cineva trebuie să-l citească și să pună valorile în mediul procesului - aplicația, o bibliotecă sau launcher-ul care pornește programul dumneavoastră. Nu puteți crea .env și presupune că de acum îl va prelua orice program. Ce anume încarcă fișierul în cazul dumneavoastră merită aflat direct, nu presupus.

Lângă el stau de obicei încă două fișiere:

# .env - rămâne doar pe mașina dumneavoastră
FIRECRAWL_API_KEY=fc-EXAMPLE-0000000000

# .env.example - șablon pentru cei care deschid proiectul
# valorile sunt goale, aici sunt doar numele
FIRECRAWL_API_KEY=

# .gitignore
.env

Rostul acestei separări e simplu. .env.example răspunde la întrebarea "de ce variabile are nevoie proiectul" și stă liniștit în depozit, pentru că nu conține valori. Cheile reale nu se mută în el nici măcar temporar.

Dacă încă nu sunteți familiarizat cu Git, aici e suficient să rețineți rolul lui .gitignore. El enumeră fișierele care nu trebuie adăugate în depozit. Lucrul cu Git și cu .gitignore îl vom analiza în detaliu la nivelul 13.

Iar acum capcana cu .gitignore, în care se cade în mod regulat. Regula se aplică doar fișierelor pe care Git încă nu le urmărește. Dacă .env a fost cândva inclus într-un commit, adăugarea unei linii în .gitignore nu îl va scoate de sub urmărire. Fișierul rămâne sub controlul versiunilor, iar modificările lui vor ajunge în continuare în commit-uri. Documentația Git o spune direct: fișierele pe care Git le urmărește deja nu sunt afectate de regulile de ignorare. Documentația gitignore.

Pe diagramă, condiția principală e la mijloc. Aceeași linie din .gitignore ajută doar cât timp .env nu este urmărit. Pentru un fișier deja urmărit e nevoie de un pas separat.

De aceea, înainte să scrieți secretul real în fișier, merită să vă asigurați că Git nu știe de el. git status va arăta dacă fișierul apare printre modificări. Dacă fișierul este deja urmărit, îl scoateți de sub urmărire cu comanda git rm --cached .env și faceți commit acestei modificări - fișierul rămâne pe disc, dar iese de sub controlul versiunilor.

Țineți cont doar că asta afectează commit-urile viitoare. O valoare care a ajuns deja în istoric rămâne acolo, iar cu ea trebuie procedat altfel - despre asta, mai jos.

Cum transmiteți cheia către conexiunea MCP

MCP este o modalitate de a conecta un instrument extern la Claude Code. Conexiunea se descrie în fișierul .mcp.json, iar acest fișier stă de obicei în depozit, lângă proiect, adică îl vede toată echipa. Prin urmare, în el nu trebuie să existe niciun secret.

O conexiune minimă a serviciului Firecrawl prin HTTP arată așa:

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

Cheia nu apare în fișier. În antet stă ${FIRECRAWL_API_KEY} - o referință la variabila de mediu după nume. Claude Code pune aici valoarea din mediul procesului în care rulează. În depozit ajunge numele, iar valoarea rămâne a fiecăruia. Claude Code poate face această înlocuire în câmpurile url, headers, env, command și args. Claude Code despre MCP.

Pe diagramă se vede că în antetul cererii se întâlnesc două lucruri venite din locuri diferite. Șablonul antetului vine din configurația comună, iar valoarea se substituie din mediul procesului. La niciun pas cheia nu este scrisă în fișierul care ajunge în depozit.

Adresa și modul de transmitere a cheii se iau din documentația serviciului. La Firecrawl este antetul Authorization, iar documentația cere explicit să nu puneți cheia în adresa MCP. Motivul e simplu. Adresa este text obișnuit, ajunge în configurație, în jurnale și în istoricul comenzilor, iar odată cu ea ajunge acolo și cheia.

Unele servicii permit autentificarea prin browser. Clientul deschide singur pagina de autentificare, iar cheia API nu mai trebuie transmisă manual deloc. Firecrawl are pentru asta o adresă separată. Documentația Firecrawl despre MCP.

Dacă instrumentul nu răspunde, verificați în ordinea următoare:

1. numele variabilei din configurație și numele pe care l-ați setat coincid până la ultimul caracter;
2. valoarea este setată în procesul din care este pornit Claude Code;
3. procesul a fost repornit după ce variabila a fost setată.

Când variabila lipsește, Claude Code nu cade în tăcere. Încarcă configurația, lasă textul ${FIRECRAWL_API_KEY} nesubstituit și afișează un avertisment cu numele variabilei lipsă. Valoarea în sine nu se afișează nicăieri, deci diagnosticul este sigur. Să afișați tot mediul ca să găsiți problema chiar nu e nevoie.

Dacă cheia s-a scurs deja

Situația e obișnuită. Cheia a ajuns într-un mesaj, într-un commit sau într-o captură de ecran. Nu e motiv de panică, dar nici de amânare. Ordinea pașilor este următoarea:

1. revocați sau înlocuiți cheia în contul dumneavoastră de la serviciu. Este singurul pas după care vechiul șir nu mai deschide nimic;
2. setați noua valoare acolo unde e nevoie de ea: local, pe hosting, în setările conexiunii;
3. ocupați-vă de locul unde a apărut cheia - ștergeți mesajul, corectați fișierul, închideți accesul;
4. verificați în cont cum a fost folosită cheia și ce arată serviciul la cheltuieli.

Ordinea este exact aceasta, iar primul pas nu se mută în altă parte. Un mesaj șters sau un commit nou peste cel vechi nu fac vechiul secret sigur. Mesajul putea fi citit, depozitul clonat, istoricul salvat. Cât timp cheia e valabilă, ea funcționează pentru toți cei care o au.

Separat, despre depozit. Dacă secretul a ajuns într-un commit, GitHub are un ghid pentru ștergerea unor astfel de date. Ștergerea datelor sensibile din depozit. Țineți însă cont că o curățare completă a istoricului rescrie commit-uri deja existente, deci îi afectează pe toți cei care lucrează cu acel depozit. O astfel de operație se stabilește împreună cu proprietarii, nu se pornește de unul singur după un articol didactic. Înlocuirea cheii se face imediat și nu trebuie convenită cu nimeni.

Ce să îi încredințați lui Claude Code

Agentul acoperă aproape toată mecanica din acest articol, cu o singură excepție. Secretul îl introduceți dumneavoastră. Este rezonabil să îi încredințați următoarele:

• să pregătească configurația cu numele variabilei, nu cu valoarea;
• să spună ce anume încarcă variabila în proces și în ce proces trebuie să ajungă;
• să verifice că secretul nu se află în build-ul pentru client și nici în fișierele urmărite de Git;
• să facă verificarea accesului și să raporteze rezultatul fără a afișa valoarea.

Dumneavoastră vă rămâne introducerea cheii reale prin mecanismul prevăzut pentru asta: introducere ascunsă în terminal, fișier local, panoul hostingului. Secretul nu ajunge niciodată în chat, într-o captură de ecran sau în raportul agentului, nici măcar "pentru o secundă, doar să verific".

Cererea poate suna cam așa:

Conectează serviciul prin API. Voi seta cheia singur.
Ia din documentație adresa, metoda și cum se transmite cheia.
În configurație pune numele variabilei de mediu, nu valoarea.
Spune ce proces ar trebui să primească variabila și ce o încarcă.
Verifică că cheia nu e în build-ul pentru client și nici în fișierele urmărite de Git.
Fă verificarea accesului fără a afișa valoarea și nici o parte din ea.
Raportează rezultatul: configurat, nesetat sau acces refuzat.

Și ultimul lucru, despre citirea raportului. "Variabila e setată" și "accesul funcționează" sunt afirmații diferite, nu le înlocuiți una cu alta. Lipsa valorii diferă și ea de refuzul serviciului. În primul caz cererea nu are cu ce fi semnată, în al doilea serviciul a răspuns, dar n-a dat acces. Dacă agentul spune doar "gata", întrebați ce anume a verificat.