API-autentisering och nyckelhantering för ElevenAPI

API-autentisering är hur en tjänst verifierar att en inkommande begäran får agera på ett konto. Till exempel, med ElevenAPI, godkänner API-uppgifter begäranden som förbrukar krediter, genererar tal och musik i stor skala och, i vissa fall, hanterar känsligt ljud.

En läckt nyckel kostar pengar och kan användas för att skapa innehåll via ditt konto. Den kan också ge för mycket åtkomst till dina plattformar, vilket kan leda till dataläckor och andra risker. Redan 2020 använde över 90 % av utvecklare API:er i minst en daglig process. Nu, med ökningen av modellprotokoll (MCP) och AI-användning, finns API:er överallt.

Den här artikeln går igenom hur du autentiserar API:er på rätt sätt och hur du hanterar nycklar genom hela deras livscykel: avgränsning, rotation, organisationskontroller, granskning och incidenthantering. Det hjälper dig att sätta upp API-autentisering och nyckelhantering på rätt sätt i ditt team. Ha gärna autentiseringsreferensen och referensen för engångstokens öppna som stöd när du läser.

Sammanfattning

• ElevenAPI autentiserar varje begäran via en enda hemlig nyckel, xi-api-key-headern. Det betyder att alla som har en nyckel kan använda krediter och generera ljud på kontot.
• Lägg aldrig in en långlivad API-nyckel i en webbläsare, mobilapp eller någon annan fil som en användare kan se. Förvara dem på en server du själv kontrollerar.
• Användningsfall på klientsidan måste autentiseras med kortlivade, engångstokens som skapas på serversidan – aldrig med den långlivade nyckeln.
• Du kan minska skadan av en läcka genom att begränsa nycklar till minsta möjliga behörighet, separera nycklar per miljö och rotera dem regelbundet.
• 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 på ett specifikt konto innan något utförs. Den som begär presenterar en uppgift, tjänsten verifierar den och ger sedan ett svar.

Enkelt uttryckt svarar det på frågan: Är den här begäran godkänd att agera för det här kontot? Det är viktigt att skilja på detta och API-auktorisering, som handlar om vad en autentiserad begäran får göra i ditt system.

Vad är nyckelhantering?

Nyckelhantering handlar om de rutiner du använder för att hantera en API-nyckel under hela dess livscykel. Det avgör hur du skapar, lagrar, använder, roterar och återkallar åtkomst till nycklar. Dessa system finns för att säkerställa API-nyckelns säkerhet från början till slut.

Med noggranna nyckelhanteringssystem kan du förhindra läckor och minska risken att nycklar blir offentliga.

Varför säkerhet för API-nycklar är viktigt: hotbilden

Nu när autentisering och nyckelhantering är definierade är det värt att vara tydlig med vad som kan gå fel om en nyckel hanteras fel. Genom att först titta på hotbilden blir det tydligt varför varje åtgärd vi går igenom är viktig: varje steg minskar antingen risken för läcka eller skadan om det händer.

ElevenAPI autentiserar via en enda hemlig mekanism: xi-api-key-headern. Alla som har nyckeln är godkända, och det finns ingen tvåfaktorskontroll på själva begäran.

Med din nyckel kan någon använda dina krediter. Text to Speech, Speech to Text, musik och ljudeffekter är alla mätbara, och en angripare med en giltig nyckel kan generera tills din kvot eller saldo är slut.

De kan generera i stor skala, och vår rate-limiting-modell gör detta mer allvarligt än det först verkar. Begränsningen baseras på samtidighet, inte bara antal begäranden per minut. En nyckel med en samtidighetsgräns på fem för en viss modellfamilj kan hantera många samtidiga genereringar, och en angripare som förstår detta kan utnyttja det maximalt.

De kan skapa innehåll i ditt namn. Allt ljud som genereras med din nyckel kopplas till din arbetsyta, och beroende på röster och indata kan det bli ett rykte- eller ibland juridiskt problem.

Sätten nycklar läcker på är vardagliga och samma som för andra typer av uppgifter:

• API-nycklar i klientkod: En nyckel som skickas med i ett webbläsarpaket, mobilapp eller single-page-app är i praktiken offentlig. Minifiering är inte skydd.
• API-nycklar i kodförråd: Hårdkodade nycklar som checkas in i Git, även privata repo som senare blir publika eller klonas, och filer som .env som aldrig skulle ha spårats.
• API-nycklar i loggar och spårning: Loggverktyg, felspårare och övervakningssystem fångar ofta HTTP-headers. En nyckel i xi-api-key hamnar i din logg, hos din APM-leverantör och hos alla med läsrättigheter.
• API-nycklar i CI och skärmdumpar: Byggloggar, supportärenden och delade terminaler.

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

Grundregeln: håll API-nycklar på serversidan

Allt annat i den här artikeln handlar om att minska riskerna med API-nycklar. Den här regeln är grunden och det viktigaste du kan göra.

Eftersom mekanismen är så enkel är grundregeln att en långlivad API-nyckel bara ska finnas på en server du kontrollerar. Den får aldrig skickas med i en webbläsare, mobilapp, desktopklient eller någon fil en användare kan ladda ner och granska. Om nyckeln finns i klientkod, räkna den som redan komprometterad.

SDK:t läser ELEVENLABS_API_KEY automatiskt, så den renaste koden skickar inget 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 ska nyckeln hämtas från en hemlighetshanterare (AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault eller motsvarande på din plattform) vid processstart – inte bakas in i en image eller en .env-fil i repo.

Engångstokens för klientappar

Grundregeln är absolut, men många legitima användningsfall kräver att klienten själv når ElevenAPI: en webbläsare som spelar upp Text to Speech, en mobilapp som spelar in ljud för transkribering och en realtidsagent i användarens flik. Den långlivade nyckeln får inte användas där. Lösningen är att ge klienten en uppgift som är låg risk om den läcker: en kortlivad engångstoken.

Din server har den långlivade nyckeln, autentiserar och godkänner användaren med din egen sessionslogik, skapar sedan en kortlivad token och skickar bara den till klienten. Tokenen går ut snabbt och är begränsad till den operation den skapades för, så en läckt token är värd lite och snart ingenting. Se referensen för engångstokens för vilka endpoints som stöds och exakt begäran.

Här är grundlogiken för ett förmedlande endpoint. Den godkänner användaren med din sessionslogik och skapar sedan en token via det dokumenterade tokens-endpointet. Begäran skickas med den långlivade xi-api-key från servern, och bara den kortlivade tokenen skickas 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 tokenen för att ansluta, och den långlivade nyckeln hamnar aldrig på sidan.

Begränsa nycklar till minsta möjliga behörighet

Minsta möjliga behörighet innebär att varje nyckel bara ska ha de rättigheter som behövs för sitt syfte – inget mer. ElevenAPI låter dig införa flera behörighetsbaserade begränsningar för vad en nyckel får och inte får göra.

En enda allsmäktig nyckel är det sämsta fallet om något läcker, och det är också det enkla standardläget. Ett bättre sätt är att utgå från att varje nyckel till slut läcker och se till att den då bara kan göra det som krävs för jobbet.

Börja med att begränsa scope, alltså vilka API-endpoints en nyckel får använda. En nyckel som bara används för transkribering behöver inte Text to Speech-åtkomst; en nyckel för musikfunktioner behöver inte hantera rösthantering.

Nästa steg är kreditkvot. Genom att sätta en egen kreditgräns per nyckel begränsar du den ekonomiska skadan vid en läcka och undviker oändliga loopar i din egen kod.

IP-whitelistning är ytterligare ett steg. Du kan begränsa en nyckel till specifika IP-adresser eller CIDR-intervall, och begäranden från andra IP-adresser får ett 403-svar. Detta är en Enterprise-funktion som just nu är i förhandsvisning och tillgänglig via din kontoansvarig.

Dela aldrig en nyckel mellan utveckling, staging och produktion. Skapa en separat nyckel per miljö, med eget scope och kvot. Nycklar per miljö gör att en läcka på en utvecklardator inte påverkar produktionskrediter, låter dig rotera en miljö utan att störa de andra och gör loggarna tydligare eftersom trafiken redan är uppdelad.

Rotation av API-nycklar

Rotation innebär att du byter ut en nyckel mot en ny med jämna mellanrum. Det är också något du gör direkt om du misstänker en läcka.

Med ett schema för rotation minskar du tiden en oupptäckt läcka kan utnyttjas. Rotation är bara smidigt om din kod är byggd för det, så planera för rotation redan från början.

Kärntekniken är överlappande nycklar, vilket ger dig ett byte utan driftstopp:

1. Skapa en ny API-nyckel: Lägg till en ny nyckel bredvid den befintliga, med samma scope, kvot och IP-begränsningar. Båda är nu giltiga.
2. Uppdatera nyckel: Byt till den nya nyckeln genom att uppdatera hemligheten i din hemlighetshanterare och låt instanserna plocka upp den (omstart, omläsning eller uppdatering beroende på din setup).
3. Bekräfta trafik: Kontrollera att trafiken går via den nya nyckeln. Se till att den gamla nyckeln är inaktiv.
4. Ta bort nyckelåtkomst: Återkalla den gamla nyckeln när den inte längre används.

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

För att överlappningen ska vara smidig, strukturera din kod så att rotation är en konfigurationsändring och aldrig en kodändring. Läs nyckeln från ett ställe där den kan uppdateras, och låt en enkel 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 överlappningen har du både PRIMARY och SECONDARY ifyllda och växlar ELEVENLABS_KEY_ACTIVE. Applikationskoden ändras aldrig.

Som standard är en rutinmässig rotation var 90:e dag rimligt för backend-nycklar, oftare för högrisk- eller ofta använda nycklar, och direkt vid exponering. Det kan automatiseras med ett schemalagt jobb som skapar, byter, verifierar och återkallar – då blir rotationen en bakgrundsprocess istället för en händelse.

Åtkomstkontroller och behörigheter för arbetsytor

Medan scope och rotation säkrar enskilda nycklar styr arbetsytans kontroller vem som kan skapa dem från början. Här kan du definiera och följa organisationspolicy, vilket påverkar all din nyckelhantering framöver.

Börja med att skilja på mänskliga och maskinella uppgifter. Personer loggar in i dashboarden med egna konton och behörigheter; tjänster autentiserar med nycklar eller, ännu bättre, servicekonton. Låt inte en tjänst köra på en nyckel skapad från en persons personliga åtkomst, och låt inte flera dela på en maskinnyckel. Anledningen är offboarding: när någon slutar eller en tjänst tas bort vill du kunna återkalla exakt rätt uppgift utan att påverka annat.

Servicekonton fyller samma syfte. De ger maskinella arbetsflöden en identitet som inte är kopplad till en person, med eget scope, vilket gör din granskningslogg korrekt.

Koppla sedan åtkomst till roller istället för till individer en och en. Arbetsytor stöder grupp- och medlemsbehörigheter just för detta. Ge minsta möjliga behörighet för att varje grupp ska kunna göra sitt, granska medlemskap regelbundet och sträva efter att ingen enskild uppgift, mänsklig eller maskinell, kan göra mer än rollen kräver.

Granskning och upptäckt

Tidigare har vi gått igenom hur du minskar skadan av en läcka. Nu handlar det om att upptäcka om en läcka har inträffat. Bra upptäckt bygger på tre vanor.

För det första: logga vilken nyckel (med identifierare, aldrig själva värdet) som hanterade vilken typ av begäran, varifrån och i vilken omfattning. Ta bort xi-api-key-headern från alla logg- och spårningslager. En regel för borttagning i din HTTP-mellanvara och i din APM-konfiguration stoppar det vanligaste sättet nycklar hamnar i loggar.

För det andra: övervaka kreditförbrukning för avvikelser. Följ kreditförbrukning per nyckel över tid och larma vid avvikelser: en plötslig topp, generering vid ovanliga tider eller en nyckel som borde vara inaktiv men plötsligt används.

För det tredje: håll koll på samtidighets-headrarna. Vi returnerar aktuellt och maximalt antal samtidiga begäranden i current-concurrent-requests och maximum-concurrent-requests-headrarna. De visar hur mycket utrymme du har, och om maxnivån ligger konstant högt utan att du själv startat det är det en stark signal om missbruk. Om du använder det råa HTTP-endpointet ser du svarshuvudena 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.

Dessa ska utlösa larm. Ett dashboard som ingen tittar på ger ingen upptäckt. Koppla kreditspikar och samtidighetslarm till samma larmväg som du använder för driftstörningar, med en tydlig ansvarig.

Incidenthantering

Även med bästa möjliga säkerhet och övervakning måste du räkna med att en nyckel till slut läcker. Att ha en plan för att begränsa skadan sparar tid och minskar påverkan.

Här är en fördefinierad incidentplan vid exponering av API-nyckel:

1. Återkalla den läckta nyckeln direkt: Vänta inte på att förstå hela omfattningen. En återkallad nyckel kan inte användas, och återkallelse är reversibel eftersom du alltid kan skapa en ny. Det är den viktigaste åtgärden.
2. Rotera till en ny nyckel: Om den läckta nyckeln användes för produktionstrafik, använd överlappningsproceduren baklänges: skapa en ny nyckel, styr över trafiken, och bekräfta sedan att den läckta nyckeln är död. Eftersom din kod läser nyckeln från konfiguration är detta bara en konfigurationsändring, inte en kodändring.
3. Bedöm skadan via användningsloggar: När läckan är stoppad, kvantifiera den. Hur länge var nyckeln giltig och exponerad? Vilka krediter användes under perioden, och stämmer mönstret med legitim trafik eller missbruk? Vilka endpoints användes?
4. Rotera beroende hemligheter: En nyckel läcker sällan ensam. Om den exponerats i ett repo, logg eller CI-pipeline, utgå från att närliggande hemligheter också är exponerade och rotera dem.
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 header-borttagning i loggern, flytta hemligheten ur byggfilen och strama åt åtkomsten till CI-systemet.
6. Skriv en post-mortem: Dokumentera tidslinje, skada, grundorsak och de konkreta åtgärder som införts (snävare scope, IP-whitelistning, hemlighetsskanner i CI och tätare rotation).

Genom att följa dessa steg har du en färdig process för att hantera incidenter med API-exponering.

Efterlevnad: SOC 2, HIPAA och datalagring

Autentisering är en del av en större efterlevnadsbedömning, och det är viktigt att vara tydlig med vad som gäller. Se detta som faktabaserad information, inte som ett beslut för just ditt fall.

ElevenLabs är SOC 2-certifierade. För vissa planer och användningsfall finns HIPAA-efterlevnad och noll-lagringsläge. Noll-lagring innebär att begärans innehåll inte sparas efter bearbetning, vilket är viktigt om dina indata eller genererat ljud är känsligt.

Om ett visst läge gäller beror på din plan, din konfiguration och vad du behandlar. Kontrollera vad som gäller för ditt konto innan du förlitar dig på något av detta, och kombinera det med åtkomstkontrollerna ovan. Efterlevnad styr hur plattformen hanterar dina data; nyckelhantering styr vem som kan agera för din räkning – och det ansvaret har du.

Så här ser bra säkerhet för API-nycklar ut

Nycklar endast på serversidan minskar risken för läckor mest. Engångstokens ger samma skydd till klienter som verkligen behöver nå vårt API. Scope och separata nycklar per miljö begränsar skadan av en läcka. Rotation i konfigurationen gör återställning till rutin. Arbetsytans kontroller skiljer på mänskliga och maskinella identiteter. Granskning gör missbruk till ett larm istället för en överraskning på fakturan. En skriftlig rutin gör en incident till en process.

Det är samma hygien som skyddar alla värdefulla hemligheter, tillämpat på en nyckel som kan spendera pengar och generera ljud i stor skala.

När du är redo att implementera detta mot riktiga begäranden hittar du aktuella endpoints i autentiseringsreferensen och referensen för engångstokens. För att förstå samtidighetsmodellen du bör övervaka, läs modellreferensen och API-quickstart.

Säkra din ElevenAPI-integration

Stark API-autentisering är en grundläggande kontroll som många andra säkerhetsrutiner bygger på. Åtgärder som att bara använda serverside-nycklar, engångstokens för klienter, minsta möjliga behörighet och inbyggd rotation i nyckelhanteringen minskar risken i stor skala.

För mer information om vilka endpoints som stöds och exakt header-format, se dokumentationen för ElevenAPI. Om du vill komma igång, begär en API-nyckel från ElevenLabs och börja bygga redan idag.

Vanliga frågor om API-autentisering och nyckelhantering