API-autentisering och nyckelhantering för ElevenAPI

API-autentisering är hur en tjänst verifierar att en inkommande begäran får agera för ett konto. Med ElevenAPI kan API-uppgifter till exempel auktorisera begäranden som använder debiterade krediter, genererar tal och musik i stor skala och i vissa driftsätt hanterar känsligt ljud. 

En läckt nyckel kostar pengar och kan användas för att generera innehåll under ditt konto. Den kan också ge alltför omfattande åtkomst till dina plattformar, vilket kan leda till dataläckor och andra attackvektorer. Redan 2020 använde över 90 % av utvecklarna API:er i minst en daglig process. Nu, med framväxten av model context protocols (MCP:er) och AI-användning, finns API:er överallt.

I den här artikeln går vi igenom hur du autentiserar API:er korrekt och hanterar nycklar under hela deras livscykel: begränsning av behörigheter, rotation, organisatoriska kontroller, granskning och incidenthantering. Den hjälper dig att konfigurera API-autentisering och nyckelhantering på rätt sätt i ditt team. Ha autentiseringsreferensen och referensen för engångstoken öppna medan du läser.

Sammanfattning

• ElevenAPI autentiserar varje begäran med en enda hemlighet, headern xi-api-key. Det innebär att alla som har en nyckel kan använda krediter och generera ljud under kontot.
• Lägg aldrig in en långlivad API-nyckel i en webbläsare, mobilapp eller någon annan artefakt som en användare kan granska. Förvara dem på en server som du kontrollerar.
• Användningsfall på klientsidan måste autentiseras med kortlivade engångstoken som utfärdas på serversidan, aldrig med den långlivade nyckeln.
• Du kan minska skadan av en läcka genom att begränsa nycklar enligt minsta behörighet, använda separata nycklar per miljö och rotera dem enligt ett schema.
• Granskning och avvikelsedetektering hjälper till att förhindra nyckelläckor och oväntade händelser.

Vad är API-autentisering?

API-autentisering är hur en tjänst bekräftar att en inkommande begäran får agera för ett specifikt konto innan den börjar arbeta. Den som skickar begäran uppger sina autentiseringsuppgifter, tjänsten verifierar dem och skickar sedan ett svar. 

Enkelt uttryckt besvarar den frågan: Är den här begäran auktoriserad att agera för det här kontot? Det är viktigt att notera att processen skiljer sig från API-auktorisering, som anger vad en autentiserad begäran får göra i ditt system.

Vad är nyckelhantering?

Nyckelhantering är den bredare uppsättning metoder du använder för att styra en API-nyckel under hela dess livscykel. Den avgör hur du skapar, lagrar, använder, roterar och återkallar åtkomst till nycklar. Systemen finns för att säkerställa en API-nyckels säkerhet från början till slut. 

Med rigorösa system för nyckelhantering kan du förhindra läckande nycklar och minska risken för att de blir offentligt tillgängliga. 

Varför API-nyckelsäkerhet är viktigt: hotmodellen

Nu när autentisering och nyckelhantering har definierats är det värt att vara tydlig med vad som går fel när en nyckel hanteras fel. Om du först granskar hotmodellen får varje efterföljande metod ett tydligt syfte: var och en minskar antingen sannolikheten för att en nyckel läcker eller skadan när den gör det.

ElevenAPI autentiserar genom en enda mekanism som bygger på en hemlighet: headern xi-api-key. Alla som har nyckeln är auktoriserade, och själva begäran har ingen andra faktor.

Med din nyckel kan de använda dina krediter. Text to Speech, Speech to Text, musik och ljudeffekter debiteras alla, och en angripare med en giltig nyckel kan generera kontinuerligt tills din kvot eller ditt saldo är slut.

De kan generera i stor skala, och vår modell för hastighetsbegränsning gör situationen mer allvarlig än den först verkar. Gränsen baseras på samtidighet, inte en enkel kvot för begäranden per minut. En nyckel i en plan med en samtidighetsgräns på fem för en viss modellfamilj kan hantera ett betydande antal samtidiga genereringar, och en angripare som förstår dessa gränser kommer att parallellisera missbruket.

De kan skapa innehåll under ditt konto. Allt ljud som genereras med din nyckel kopplas till din arbetsyta, och beroende på vilka röster och indata som används kan det skada ditt rykte och ibland få juridiska följder.

Sätten som nycklar läcker på är vardagliga och samma fel orsakar läckor av alla andra typer av autentiseringsuppgifter:

• API-nycklar i kod på klientsidan: En nyckel som skickas med i ett webbläsarpaket, en mobil binärfil eller en ensidesapp är i praktiken offentlig. Minifiering är inte obfuskering.
• API-nycklar i kodarkiv: Hårdkodade nycklar som checkas in i Git, inklusive privata repor som senare blir offentliga eller klonas i stor omfattning, samt filer som .env som aldrig var avsedda att versionshanteras.
• API-nycklar i loggar och spårningar: Begärandeloggare, felspårare och observability-pipelines fångar rutinmässigt HTTP-headers. En nyckel i xi-api-key hamnar i din logglagring, hos din APM-leverantör och hos alla som har läsåtkomst till någon av dem.
• API-nycklar i CI och skärmdumpar: Byggloggar, supportärenden och delade terminaler.

Varje avsnitt nedan handlar om att minska sannolikheten eller effekten av någon av dessa risker.

Grundregeln: förvara API-nycklar på serversidan

Allt annat i artikeln ger insikter om hur du minskar riskerna med API-nyckelautentisering och -hantering. Den här regeln är grunden för allt det och bör prioriteras framför allt annat.

Eftersom mekanismen är så enkel är grundregeln att en långlivad API-nyckel endast hör hemma på en server som du kontrollerar. Den får aldrig skickas med i en webbläsare, mobilapp, skrivbordsklient eller annan artefakt som en användare kan ladda ner och granska. Om nyckeln finns i kod på klientsidan ska du behandla den som redan komprometterad.

SDK:t läser ELEVENLABS_API_KEY automatiskt, så den renaste koden skickar inte in något alls och initierar klienten en gång.

import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

// Reads process.env.ELEVENLABS_API_KEY when apiKey is omitted - never a literal.
const elevenlabs = new ElevenLabsClient();

const audio = await elevenlabs.textToSpeech.convert("JBFqnCBsd6RMkjVDRZzb", {
  text: "Generated entirely server-side.",
  modelId: "eleven_flash_v2_5",
  outputFormat: "mp3_44100_128",
});

I produktion bör den hämtas från en hemlighetshanterare (AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault eller motsvarande för din plattform) vid processstart, inte bakas in i en avbildning eller i en .env-fil som checkas in i repot.

Engångstoken för appar på klientsidan

Grundregeln är absolut, men i många legitima användningsfall behöver klienten själv nå ElevenAPI: en webbläsare som spelar upp strömmad Text to Speech, en mobilapp som fångar ljud för transkribering och en realtidsagent som körs i användarens flik. Den långlivade nyckeln kan inte användas där. Lösningen är att ge klienten en autentiseringsuppgift med låg risk vid läcka: en kortlivad engångstoken.

Din server lagrar den långlivade nyckeln, autentiserar och auktoriserar användaren med din egen sessionslogik, utfärdar sedan en kortlivad token och ger bara den till klienten. Tokenen upphör snabbt att gälla och är begränsad till den åtgärd den utfärdades för, så en läckt token är snart värdelös. Se referensen för engångstoken för vilka endpoints som stöds och det exakta begärandeformatet.

Här är den grundläggande logiken för en broker-endpoint. Den auktoriserar användaren med din egen sessionslogik och utfärdar sedan en token via den dokumenterade token-endpointen. Begäran skickas från servern med den långlivade xi-api-key, och endast den kortlivade token som skapas skickas tillbaka till klienten.

// ... express app and route boilerplate
app.post("/api/voice-token", async (req, res) => {
  // 1. Authorize the user with YOUR session/auth system first.
  if (!req.session?.user) return res.status(401).json({ error: "unauthorized" });

  // 2. Mint a short-lived token server-side. The long-lived key travels only
  //    in this server-to-server request, never to the browser.
  const response = await fetch("https://api.elevenlabs.io/v1/tokens", {
    method: "POST",
    headers: {
      "xi-api-key": process.env.ELEVENLABS_API_KEY as string,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({}), // populate per the tokens reference
  });

  // 3. Return only the short-lived token. The API key never leaves the server.
  res.json({ token: await response.json() });
});

Webbläsaren använder sedan den tokenen för att ansluta, och den långlivade nyckeln hamnar aldrig på sidan.

Begränsa nycklar enligt minsta behörighet

Minsta behörighet är principen att varje nyckel bara ska ha de behörigheter som dess uppgift kräver, och inget mer. ElevenAPI låter dig införa flera behörighetsbaserade begränsningar som styr vad en nyckel kan och inte kan göra.

En enda nyckel med fullständig behörighet är det värsta scenariot vid en läcka, och det är också det enkla standardvalet. Ett bättre tillvägagångssätt är att utgå från att varje enskild nyckel till slut kommer att läcka och se till att den då bara kan göra det som uppgiften kräver.

Börja med att begränsa omfattningen, vilket styr vilka API-endpoints en nyckel kan anropa. En nyckel som bara används för transkribering behöver inte åtkomst till Text to Speech; en nyckel för en musikfunktion behöver inte hantera rösthantering.

Nästa steg är kreditkvoten. En anpassad kreditgräns per nyckel begränsar den ekonomiska skadan av en läcka och motverkar samtidigt skenande loopar i din egen kod.

IP-vitlistning går längre. Du kan begränsa en nyckel till specifika IP-adresser eller CIDR-intervall, och begäranden från IP-adresser som inte är vitlistade avvisas med en 403. Detta är en Enterprise-funktion som för närvarande är i förhandsversion och tillgänglig via din account manager.

Dela slutligen inte en nyckel mellan utveckling, staging och produktion. Utfärda en separat nyckel för varje miljö, med egen omfattning och kvot. Nycklar per miljö håller en läcka från en utvecklares laptop borta från produktionskrediter, låter dig rotera en miljö utan att störa de andra och gör användningsloggarna lättare att tolka eftersom trafiken redan är uppdelad efter ursprung.

Rotation av API-nycklar

Nyckelrotation innebär att regelbundet ersätta en nyckel med en ny. Det är också en åtgärd du kan vidta när du misstänker ett intrång eller en exponering.

En regelbunden rotation minskar också tidsfönstret då en oupptäckt läcka kan utnyttjas. Rotation är bara smidig om din kod är byggd för den, så planera för rotation innan du behöver den.

Den centrala tekniken är överlappande nycklar, vilket ger en övergång utan driftstopp:

1. Skapa en ny API-nyckel: Tillhandahåll en ny nyckel parallellt med den befintliga, med samma omfattning, kvot och IP-begränsningar. Båda är nu giltiga.
2. Uppdatera nyckeln: Rulla ut den nya nyckeln genom att uppdatera hemligheten i din hemlighetshanterare och låta instanserna hämta den, genom en omstart, ny inläsning eller uppdatering från hemlighetshanteraren beroende på din konfiguration.
3. Bekräfta trafik: Kontrollera att trafiken går via den nya nyckeln. Följ användningen för att bekräfta att den gamla nyckeln inte längre används.
4. Ta bort nyckelåtkomst: Återkalla den gamla nyckeln när den inte har haft någon trafik under ett säkert tidsfönster.

Eftersom båda nycklarna är giltiga under överlappningen finns det aldrig ett tillfälle då begäranden misslyckas på grund av att autentiseringsuppgifter saknas. Överlappningsfönstret har ytterligare en fördel: en felkonfigurerad instans avslöjar sig genom att fortsätta använda den gamla nyckeln, så att du kan hitta den innan du stänger av nyckeln.

För att överlappningen ska vara odramatisk ska du strukturera koden så att rotation är en konfigurationsändring, aldrig en kodändring. Läs in nyckeln från ett ställe där den kan uppdateras, och låt en enda växel avgöra vilken hemlighet som är aktiv.

// Rotation is driven by configuration, not code edits. The secret manager (or
// the deploy that injects env vars) is the single point of change.
// ELEVENLABS_KEY_ACTIVE selects which slot is live, enabling overlap.
let client: ElevenLabsClient | undefined;

function activeKey(): string {
  const slot = process.env.ELEVENLABS_KEY_ACTIVE ?? "primary";
  const name = slot === "primary" ? "ELEVENLABS_API_KEY_PRIMARY" : "ELEVENLABS_API_KEY_SECONDARY";
  return process.env[name] as string;
}

function getClient(): ElevenLabsClient {
  return (client ??= new ElevenLabsClient({ apiKey: activeKey() }));
}

// Call after a secret refresh to pick up the rotated key without a deploy.
function resetClient(): void {
  client = undefined;
}

Under en överlappning håller du både PRIMARY och SECONDARY ifyllda och växlar ELEVENLABS_KEY_ACTIVE. Applikationskoden ändras aldrig.

Som intervall är rutinmässig rotation var 90:e dag en rimlig standard för backend-nycklar, oftare för nycklar med högt värde eller bred åtkomst och omedelbart vid exponering. Detta kan automatiseras med ett schemalagt jobb som tillhandahåller, rullar ut, verifierar och återkallar, vilket gör rotation till en bakgrundsprocess i stället för en särskild händelse.

Åtkomstkontroller och behörigheter för arbetsytor

Medan begränsning och rotation säkrar enskilda nycklar styr arbetsytekontroller vem som från början kan utfärda dem. Där kan du definiera och följa organisatoriska policyer som sedan påverkar all din framtida nyckelhantering.

Börja med att skilja mellan autentiseringsuppgifter för människor och maskiner. Människor loggar in på dashboarden med sina egna konton och behörigheter; tjänster autentiserar med nycklar eller, ännu hellre, tjänstkonton. Låt inte en tjänst köras med en nyckel som utfärdats från en persons personliga åtkomst, och låt inte människor dela en och samma maskinnyckel. Anledningen är avveckling: när en person slutar eller en tjänst tas ur drift vill du återkalla exakt rätt autentiseringsuppgift utan följdskador.

Tjänstkonton tjänar samma syfte. De ger maskinarbetslaster en identitet som inte är knuten till en människa, med egna begränsningar, vilket gör ditt granskningsspår tillförlitligt.

Koppla sedan åtkomst till roller i stället för till individer en i taget. Arbetsytor har behörigheter för grupper och medlemmar just för detta. Ge varje grupp minsta behörighet för att kunna utföra sitt arbete, granska medlemskap regelbundet och sträva efter en struktur där ingen enskild autentiseringsuppgift, mänsklig eller maskinell, kan göra mer än rollen kräver.

Granskning och upptäckt

I de tidigare avsnitten har vi beskrivit hur du minskar skadan av en läcka. I det här avsnittet går vi igenom hur du upptäcker om en läcka har skett överhuvudtaget. Bra upptäckt bygger på tre vanor. 

Den första är att registrera vilken nyckel, via identifierare och aldrig hemlighetens värde, som hanterade vilken typ av begäran, varifrån och i vilken volym. Rensa bort headern xi-api-key från alla lager för loggning och spårning. En maskeringsregel i din HTTP-mellanprogramvara och APM-konfiguration stoppar det vanligaste sättet som nycklar hamnar i logglagring på.

Den andra är att övervaka kreditanvändning för avvikelser. Följ kreditförbrukningen per nyckel över tid och varna vid avvikelser från baslinjen: en plötslig ökning, generering vid ovanliga tider eller en nyckel som ska vara inaktiv men plötsligt blir aktiv.

Den tredje är att bevaka headers för samtidighet. Vi returnerar aktuella och maximala samtidiga begäranden i varje svar, i headersarna current-concurrent-requests och maximum-concurrent-requests. De visar hur mycket kapacitet du har kvar, och en varaktig nivå vid maximigränsen som du inte själv har initierat är en stark signal om missbruk. Om du använder den råa HTTP-endpointen exponeras svarsheaders direkt:

const resp = await fetch("https://api.elevenlabs.io/v1/text-to-speech/JBFqnCBsd6RMkjVDRZzb", {
  method: "POST",
  headers: {
    "xi-api-key": process.env.ELEVENLABS_API_KEY as string,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ text: "Monitoring headroom.", model_id: "eleven_flash_v2_5" }),
});

const current = resp.headers.get("current-concurrent-requests");
const maximum = resp.headers.get("maximum-concurrent-requests");
// Emit these to your metrics pipeline; alert on sustained saturation you did not cause.

Det här bör utlösa varningar. En dashboard som ingen tittar på ger ingen upptäckt. Koppla signaler för ökade kredituttag och mättad samtidighet till samma larmflöde som du använder för driftstörningar, med en tydligt ansvarig.

Incidenthantering

Även med bästa möjliga system för säkerhet och övervakning måste du utgå från att en nyckel till slut kommer att läcka. Genom att planera för det med en lista över åtgärder för att begränsa skadan får du en handlingsplan som sparar tid och minskar påverkan.

Här är en fördefinierad process för incidenthantering vid exponering av API-nycklar:

1. Återkalla den läckta nyckeln omedelbart: Vänta inte på att förstå hela omfattningen. En återkallad nyckel kan inte generera något, och återkallandet är reversibelt i den meningen att du alltid kan utfärda en ersättningsnyckel. Detta är den enskilt viktigaste åtgärden.
2. Rotera till en ny nyckel: Om den läckta nyckeln hanterade produktionstrafik använder du överlappningsprocessen i omvänd ordning: skapa en ny nyckel, flytta över trafiken och bekräfta sedan att den läckta nyckeln är avstängd. Eftersom koden läser nyckeln från konfigurationen är detta en konfigurationsändring, inte en kodändring.
3. Bedöm skadans omfattning från användningsloggar: När läckan är begränsad ska du kvantifiera den. Hur länge var nyckeln giltig och exponerad? Vilka krediter användes under perioden, och motsvarar mönstret legitim trafik eller missbruk? Vilka endpoints berördes?
4. Rotera beroende hemligheter: En nyckel läcker sällan ensam. Om den exponerades i ett repo, en logglagring eller en CI-pipeline ska du anta att närliggande hemligheter på samma plats också är exponerade och rotera dem också.
5. Stäng läckvägen: Ta reda på hur nyckeln läckte och åtgärda det, annars händer det igen: lägg till filen i .gitignore och rensa historiken, lägg till maskering av headers i loggaren, flytta hemligheten ur byggartefakten och begränsa åtkomsten till CI-systemet.
6. Skriv en post-mortem: Dokumentera tidslinjen, skadans omfattning, grundorsaken och de konkreta kontroller som har lagts till, exempelvis snävare omfattning, IP-vitlistning, en hemlighetsskanner i CI och tätare rotation.

Genom att följa de här stegen har du en etablerad process för katastrofscenarier med exponerade API:er. 

Efterlevnadsstatus: SOC 2, HIPAA och datalagring

Autentisering är en del av en bredare bedömning av regelefterlevnad, och det är viktigt att vara noggrann med vad som kan och inte kan hävdas här. Se följande som faktabaserade utgångspunkter, inte som en bedömning för just ditt användningsfall.

ElevenLabs är SOC 2-kompatibelt. För kvalificerade planer och användningsfall finns HIPAA-efterlevnad och lägen utan datalagring. Ingen datalagring innebär att innehållet i begäran inte lagras efter bearbetning, vilket är viktigt när dina indata eller ditt genererade ljud är känsliga.

Om ett visst läge gäller beror på din plan, din konfiguration och detaljerna i det du bearbetar. Bekräfta behörighet och exakta villkor för ditt konto innan du förlitar dig på något av dem, och kombinera dem med åtkomstkontrollerna som beskrivs ovan. Efterlevnadscertifieringar styr hur plattformen hanterar dina data; nyckelhantering styr vem som kan agera för din räkning, och den delen ansvarar du för.

Så ser bra API-nyckelsäkerhet ut

Nycklar som endast finns på serversidan tar bort den största läckytan. Engångstoken utökar den garantin till klienter som verkligen behöver nå vårt API. Begränsad omfattning och uppdelning per miljö begränsar skadan av varje enskild läcka. Rotation inbyggd i konfigurationen gör återhämtning till rutin i stället för en risk. Arbetsytekontroller håller mänskliga och maskinella identiteter åtskilda. Granskning förvandlar missbruk till en varning i stället för en oväntad kostnad på fakturan. En skriftlig driftmanual gör en incident till en procedur.

Det är samma sunda hantering av autentiseringsuppgifter som skyddar alla värdefulla hemligheter, tillämpad på en nyckel vars särskilda värde är att den kan spendera pengar och generera ljud i stor skala.

När du är redo att koppla detta till de verkliga begärandeformaten innehåller autentiseringsreferensen och referensen för engångstoken den aktuella listan över endpoints som stöds. För att förstå samtidighetsmodellen som din övervakning bör följa är modellreferensen och API-snabbstarten rätt nästa läsning.

Säkra din ElevenAPI-integration

Stark API-autentisering är en grundläggande kontroll som många andra säkerhetsmetoder bygger på. Åtgärder som att enbart använda nycklar på serversidan, använda engångstoken för klienter, begränsa enligt minsta behörighet och bygga in rotation i nyckelhanteringen hjälper till att förebygga risker i stor skala.

Mer information om endpoints som stöds och exakt headerformat finns i ElevenAPI-dokumentationen. Om du är redo att komma igång kan du begära en API-nyckel från ElevenLabs och börja bygga i dag. 

Vanliga frågor om API-autentisering och nyckelhantering