Ustvarite in zavarujte svoj ključ API
Na tej strani
Poverilnica, ki overja vaše zahteve
Vaš ključ API overi vsak zahtevek, poslan modelom Mistral: brez njega noben klic ni sprejet. Razmišljajte o njem kot o tehničnem geslu, razen da potuje skozi kodo, konfiguracijske datoteke in cevovode za uvajanje, kar pomeni, da se konča na veliko več mestih kot običajno geslo. Vsakdo, ki ga ima, lahko porabi vašo kvoto in ustvari stroške na vašem računu.
Ustvarite svoj prvi ključ
V konzoli Mistral odprite svoj delovni prostor in v stranski vrstici pojdite v razdelek API Keys. Kliknite Create new key in mu dajte opisno ime, na primer dev-chatbot-mars-2026. To ime nima tehnične funkcije, rešilo pa vam bo kožo, ko bo na seznamu soobstajalo šest ključev in boste morali preklicati le enega: „ključ 3” vam ne pove ničesar, medtem ko vam dev-chatbot-mars-2026 pove vse.
Ključ se prikaže samo enkrat, in sicer ob trenutku ustvarjanja. Takoj ga kopirajte in shranite na varno mesto. Če okno zaprete, preden ga kopirate, ga ni mogoče obnoviti: ustvariti morate novega. Ključ Mistral je sestavljen iz predpone, ki ji sledi dolg alfanumerični niz. Ne zamenjajte ga z ID-jem delovnega prostora ali žetonom JWT: za razliko od slednjega ne poteče sam od sebe in velja, dokler ga ne prekličete.
Shranjevanje brez trdega kodiranja
Zlato pravilo je preprosto: nikoli ne kodirajte svojega ključa API neposredno v izvorno kodo. Ko ta datoteka pristane v skupnem skladišču, ključ potuje z njo. Namesto tega vedno uporabite spremenljivko okolja.
V sistemih Linux in macOS jo deklarirajte v terminalu:
export MISTRAL_API_KEY="your-api-key-here"
Ta spremenljivka izgine, ko zaprete terminal; da bo trajna, dodajte vrstico v datoteko ~/.bashrc, ~/.zshrc ali ~/.profile.
V sistemu Windows je ekvivalent v PowerShellu videti takole:
$env:MISTRAL_API_KEY = "your-api-key-here"
In da preživi ponovni zagon seje:
[System.Environment]::SetEnvironmentVariable("MISTRAL_API_KEY", "your-api-key-here", "User")
V projektni aplikaciji je najpogostejša praksa ustvarjanje datoteke .env v korenski mapi:
MISTRAL_API_KEY=your-api-key-here
Datoteko .env takoj dodajte v .gitignore – pred prvim potrditvijo (commit), ne po njem. V Pythonu knjižnica python-dotenv prebere to datoteko in ob zagonu vbrizga spremenljivke, kar vam omogoča udobje lokalne datoteke brez tveganja različičenja skrivnosti.
Rotacija ključev
Ključ zamenjate iz treh razlogov. Takoj, če je bil kakorkoli razkrit: potrditev (commit), poslana v javno skladišče Git, naglo sporočilo v Slacku ali sledi v dnevnikih strežnika. Redno v produkcijskem okolju, pri čemer je vsakih devetdeset dni razumen ritem. In ko sodelavec odide, ki je imel dostop, in sicer isti dan, ko vrne svojo izkaznico.
Postopek se izogne prekinitvi storitve, če spoštujete vrstni red:
- Ustvarite nov ključ v konzoli
- Posodobite spremenljivko okolja v vseh svojih uvajanjih
- Preverite, ali vse deluje z novim ključem
- Prekličite stari ključ šele po tem preverjanju
Zamenjava korakov 3 in 4 je klasična napaka: najprej prekličete ključ „zaradi varnosti”, šele nato pa odkrijete, da je pozabljena storitev še vedno uporabljala stari ključ. Ta rotacija brez zastoja zagotavlja, da med prehodom nobena komponenta ne odpove.
Zmanjšanje površine izpostavljenosti
Če več aplikacij kliče API, ustvarite en ključ na aplikacijo. Če je eden ogrožen, morate preklicati le ta specifični ključ, ne da bi ustavili druge. Po istem principu nikoli ne uporabljajte produkcijskega ključa v razvojnem okolju: to je ravno okolje, kjer skrivnosti krožijo najbolj svobodno.
Nato spremljajte uporabo iz konzole, ki prikazuje dnevnike uporabe za vsak ključ. Nenaden skok v žetonih ali klicih z neznanega IP-naslova mora sprožiti takojšnjo rotacijo, brez čakanja na potrditev incidenta.
Omeniti velja še tri končne napake, saj se z njimi srečujemo vsak teden. Ključ, objavljen v javnem skladišču Git, ostane berljiv v zgodovini tudi po izbrisu datoteke: edini veljaven odziv je preklic. Ključ, poslan v nešifrirani obliki po e-pošti ali instant sporočilih, je za vedno arhiviran na strežnikih, ki jih ne nadzorujete. In ključ, ki je potekel ali preklican, a še vedno ostaja v uvajanju, povzroča napake 401 Unauthorized, katerih diagnosticiranje pogosto traja uro preprosto zato, ker se nihče ni spomnil preveriti.
Ključne ugotovitve
- Svoje ključe ustvarite v razdelku API Keys svojega delovnega prostora v konzoli Mistral
- Shranjujte jih izključno v spremenljivkah okolja ali upravitelju skrivnosti
- Izvajajte redno rotacijo in takojšnjo rotacijo v primeru razkritja
- Ustvarite en ključ na aplikacijo, da omejite vpliv morebitne ogroženosti
- Vedno dodajte
.envv svoj.gitignore