Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Todennus bearer-tokenilla

Oppitunti 14 / 14 Päivitetty 30. heinäkuuta 2026 Kehittäjä
Tällä sivulla
  1. Suojaa API-kutsusi
  2. Bearer-token-järjestelmä
  3. Todennusvirheet
  4. Turvallisuuden parhaat käytännöt
  5. Vuotojen havaitseminen
  6. HTTPS on pakollinen
  7. Keskeiset asiat
  8. Testaa ymmärryksesi

Suojaa API-kutsusi

Aloitusopas xAI:n dokumentaatiossa Jokaisen xAI-rajapinnalle lähetetyn pyynnön on oltava todennettu. Rajapinta käyttää Bearer token -järjestelmää, joka on REST-rajapinnoissa laajalti käytetty standardi. Tässä oppitunnissa selitetään, miten mekanismi toimii, ja käydään läpi parhaat käytännöt avainten suojaamiseen tuotantoympäristössä.

Bearer-token-järjestelmä

Nimensä mukaisesti kuka tahansa, jolla on token hallussaan (“bearer”), pääsee käyttämään rajapintaa. Siksi avaimesi suojaaminen on ensiarvoisen tärkeää: tunnistautumista varten ei tarvita muuta kuin itse token.

Otsikon muoto

Jokaisen HTTP-pyynnön on sisällettävä Authorization-otsikko, jossa on etuliite Bearer ja sen perässä avaimesi:

Authorization: Bearer xai-your-api-key

cURLilla tämä näyttää seuraavalta:

curl https://api.x.ai/v1/responses \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "grok-4.5", "input": "Hello"}'

Pythonissa SDK:t hoitavat tämän otsikon automaattisesti, kun välität avaimen asiakasohjelman muodostimelle.

Todennusvirheet

HTTP 401 Unauthorized

Tämä virhe tarkoittaa, että avaimesi puuttuu, on virheellinen tai on mitätöity. Tarkista seuraavat asiat:

  • Onko ympäristömuuttuja XAI_API_KEY asetettu
  • Alkaako avain merkkijonolla xai-
  • Onko avain mitätöity konsolissa

HTTP 403 Forbidden

Avaimesi on kelvollinen, mutta sillä ei ole oikeuksia pyydettyyn toimintoon. Tämä voi johtua esimerkiksi tiimin asettamista rajoituksista tietyille toiminnoille.

Turvallisuuden parhaat käytännöt

Älä koskaan paljasta avainta koodissa

Avaimet eivät saa koskaan esiintyä selväkielisinä seuraavissa paikoissa:

  • Versionhallituissa lähdekoodissa (Git)
  • Sovelluslokeissa
  • URL-osoitteissa tai kyselyparametreissa
  • Käyttäjille näytetyissä virheilmoituksissa
  • GitHub-ongelmissa (issues) ja vetopyynnöissä (pull requests)

Käytä salaisuuksien hallintajärjestelmää

Tuotantoympäristössä avaimet tulee tallentaa erityiseen järjestelmään:

  • AWS Secrets Manager tai Parameter Store
  • Google Secret Manager
  • Azure Key Vault
  • HashiCorp Vault
  • CI/CD-alustasi salaisuudet (GitHub Actions, GitLab CI)

Avainten kierrätys

Vaihda avaimiasi säännöllisesti ja välittömästi, jos epäilet vuotoa:

  1. Luo uusi avain xAI-konsolissa
  2. Päivitä avain salaisuuksien hallintajärjestelmääsi
  3. Ota sovelluksesi uudelleen käyttöön
  4. Varmista, että kaikki toimii uudella avaimella
  5. Mitätöi vanha avain konsolissa

Rajoita oikeuksia

Jos työskentelet tiimissä, luo erilliset avaimet jokaiselle palvelulle ja ympäristölle. Jos yksi avain vaarantuu, vaikutukset rajoittuvat yhteen kontekstiin.

Vuotojen havaitseminen

Etuliite xai- mahdollistaa sen, että havaitsemistyökalut (kuten GitHubin salaisuuksien skannaus, GitGuardian, TruffleHog) tunnistavat avaimet lähdekoodista automaattisesti. Ota nämä työkalut käyttöön repositorioissasi, jotta saat välittömän hälytyksen, jos avain paljastuu vahingossa.

Jos avain havaitaan julkisessa commitissa:

  1. Mitätöi se välittömästi xAI-konsolissa
  2. Tarkista käyttöhistoriasi luvattoman käytön varalta
  3. Luo uusi avain
  4. Siivoa Git-historiasi (tai vielä parempi: pidä avainta vaarantuneena ja siirry eteenpäin)

HTTPS on pakollinen

xAI-rajapinta hyväksyy vain HTTPS-yhteydet. TLS salaa pyyntösi siirron aikana, mukaan lukien Authorization-otsikon. Älä koskaan yritä kiertää tätä suojaa: salaamaton HTTP-pyyntö paljastaisi avaimesi verkossa.

Keskeiset asiat

  • Rajapinta käyttää Bearer token -järjestelmää Authorization-otsikon kautta
  • Avain on ainoa todennustekijä: suojaa sitä kuin salasanaa
  • Käytä tuotannossa salaisuuksien hallintajärjestelmää äläkä koskaan koodaa avainta suoraan lähdekoodiin
  • Ota käyttöön vuotojen havaitseminen Git-repositorioissasi
  • Kierrätä avaimia säännöllisesti ja mitätöi vaarantuneet avaimet välittömästi

Testaa ymmärryksesi

xAI-rajapinnan perusteet: viimeinen tarkistus ennen rakentamisen aloittamista.

1. Mitä sinun tulee tehdä API-avaimelle heti sen luomisen jälkeen?

Vastaus: Tallenna se turvalliseen paikkaan (se näytetään vain kerran), altista se XAI_API_KEY-muuttujan kautta äläkä koodaa sitä suoraan lähdekoodiin, käytä yhtä avainta per ympäristö ja testaa se heti kutsumalla osoitetta /v1/models.

2. Mikä on perus-URL-osoite, ja miksi se on niin tärkeä?

Vastaus: https://api.x.ai/v1. Se mahdollistaa yhteensopivuuden OpenAI:n kanssa: base_url:n ja avaimen vaihtaminen riittää ohjaamaan olemassa olevan OpenAI-koodin käyttämään Grokia.

3. Mitä SDK:ita voit käyttää Grokin kanssa?

Vastaus: Natiivi xAI SDK, OpenAI SDK (käyttäen xAI:n base_url:ää) ja Vercel AI SDK JavaScript-puolella sekä cURL testaamiseen: ekosysteemi on avoin.

4. Mikä on tärkein generointipäätepiste?

Vastaus: POST /v1/responses, joka on nykyaikainen muoto; chat/completions on edelleen saatavilla yhteensopivuussyistä vanhentuneena vaihtoehtona.

5. Miten jokainen pyyntö todennetaan?

Vastaus: Authorization: Bearer -otsikolla ja xai-…-avaimella: standardi Bearer token -järjestelmä, sama riippumatta käytetystä SDK:sta tai työkalusta.

Suojattu avain, perus-URL-osoite, valittu SDK ja Bearer kaikkialla: perusta on kunnossa, ja seuraavat API-kurssit rakentuvat sen päälle.