Hoppa till huvudinnehåll
Svenska— Välj ett språk
Meny

Autentisering och tillfälliga token

Lektion 2 av 16 Uppdaterad 30 juli 2026 Utvecklare
På denna sida
  1. Två sätt att autentisera
  2. Rekommenderad arkitektur med tillfälliga token
  3. Bästa praxis för säkerhet
  4. Viktiga punkter

Två sätt att autentisera

Voice Agent API erbjuder två metoder för att autentisera din WebSocket-anslutning. Vilken du väljer beror på var din kod körs: på servern eller på klienten.

Direkt API-nyckel (serversida)

Den enklaste metoden är att skicka din API-nyckel i auktoriseringsheadern när du öppnar WebSocket-anslutningen. Detta fungerar för serverapplikationer där nyckeln förblir skyddad:

const ws = new WebSocket("wss://api.x.ai/v1/realtime", {
  headers: {
    "Authorization": "Bearer xai-your-api-key"
  }
});

Använd aldrig denna metod i kod som körs i webbläsaren: API-nyckeln skulle då exponeras i källkoden eller utvecklarverktygen.

Tillfälliga token (klientsida)

För frontend-applikationer (webbläsare, mobil) tillhandahåller xAI tillfälliga token. Din backend genererar en kortlivad token som du sedan skickar till klienten för att öppna WebSocket-anslutningen.

Du skapar en token med en POST-förfrågan:

curl -X POST "https://api.x.ai/v1/realtime/client_secrets" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"expires_after": {"seconds": 300}}'

Fältet expires_after.seconds anger hur länge token är giltig, i sekunder. Exemplet i den officiella dokumentationen använder 300 sekunder (5 minuter): en tillfällig token är avsedd att täcka en röstsession, inte att bestå evigt. Sikta på den kortaste giltighetstid som fungerar för dina sessioner.

Rekommenderad arkitektur med tillfälliga token

Här är det kompletta flödet för en webbapplikation:

// 1. Serversida (Node.js/Express): generera token
app.post("/api/realtime-token", async (req, res) => {
  const response = await fetch(
    "https://api.x.ai/v1/realtime/client_secrets",
    {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${process.env.XAI_API_KEY}`,
        "Content-Type": "application/json"
      },
      body: JSON.stringify({ expires_after: { seconds: 600 } })
    }
  );
  // Returnera xAI:s svarsbody oförändrad;
  // den innehåller den tillfälliga token
  res.json(await response.json());
});

// 2. Klientsida (webbläsare): använd token
// Webbläsarens WebSocket-konstruktor accepterar inte headers:
// token skickas istället i ett SUBPROTOCOL, prefixat med "xai-client-secret."
async function startVoiceSession(ephemeralToken) {
  const ws = new WebSocket(
    "wss://api.x.ai/v1/realtime",
    [`xai-client-secret.${ephemeralToken}`]
  );

  ws.onopen = () => {
    console.log("Voice session started");
  };
}

Förnyelse av token

Dokumentationen specificerar inte huruvida en token som löper ut stänger en redan öppen anslutning. Oavsett vilket behöver din applikation en plan för när anslutningen bryts: övervaka close-händelsen, be din backend om en ny token och återanslut sedan:

ws.onclose = async () => {
  // Anslutningen förlorades eller stängdes: begär en ny token
  const newToken = await fetchNewToken();
  reconnect(newToken);
};

Bästa praxis för säkerhet

Några grundläggande regler håller dina anslutningar säkra:

  • Exponera aldrig din huvudsakliga API-nyckel på klienten
  • Håll giltighetstiden (expires_after.seconds) så kort som möjligt: om din genomsnittliga session varar i fem minuter räcker 300 till 600 sekunder
  • Validera token-förfrågningar på servern (användarautentisering, hastighetsbegränsning)
  • Logga skapandet av token så att du kan upptäcka onormal användning
  • Rotera din huvudsakliga API-nyckel om du misstänker att den har äventyrats

Viktiga punkter

  • En direkt API-nyckel passar endast för serverapplikationer
  • Tillfälliga token är ett måste för klientsidans applikationer (webbläsare, mobil)
  • Ställ in token giltighetstid med expires_after.seconds och håll den kort (300 sekunder i det officiella exemplet)
  • Det rekommenderade flödet: din backend genererar token och din frontend skickar den som subprotokollet xai-client-secret. för att öppna WebSocket
  • Planera alltid för automatisk förnyelse av token