API-authenticatie en sleutelbeheer voor ElevenAPI

API-authenticatie is de manier waarop een service controleert of een binnenkomend verzoek namens een account mag handelen. Met ElevenAPI autoriseren API-credentials bijvoorbeeld verzoeken die credits op basis van gebruik verbruiken, op schaal spraak en muziek genereren en, in sommige implementaties, gevoelige audio verwerken. 

Een gelekte sleutel kost geld en kan worden gebruikt om content onder je account te genereren. De sleutel kan ook te ruime toegang tot je platforms bieden, met kans op datalekken en andere aanvalsvectoren. Al in 2020 gebruikte meer dan 90% van de ontwikkelaars API's in minstens één dagelijks proces. Door de opkomst van model context protocols (MCP's) en AI-gebruik zijn API's nu werkelijk overal.

Dit artikel behandelt hoe je API's correct authenticeert en hoe je sleutels gedurende hun volledige levenscyclus beheert: afbakening, rotatie, organisatorische controles, audits en incidentrespons. Het helpt je om API-authenticatie en sleutelbeheer goed in je team in te richten. Houd tijdens het lezen de authenticatiereferentie en de referentie voor tokens voor eenmalig gebruik bij de hand.

Samenvatting

• ElevenAPI authenticeert elk verzoek met één geheim, de header xi-api-key. Iedereen die een sleutel bezit, kan credits besteden en audio genereren onder het account.
• Neem nooit een API-sleutel met lange geldigheid op in een browser, mobiele app of ander artefact dat een gebruiker kan inspecteren. Bewaar deze op een server die je beheert.
• Gebruiksscenario's aan de clientzijde moeten authenticeren met kort geldige tokens voor eenmalig gebruik die server-side worden aangemaakt, en nooit met de sleutel met lange geldigheid.
• Je kunt de impact van een lek beperken door sleutels volgens het least-privilegeprincipe af te bakenen, sleutels per omgeving te scheiden en ze volgens een schema te roteren.
• Audits en anomaliedetectie helpen sleutellekken en onverwachte gebeurtenissen te voorkomen.

Wat is API-authenticatie?

API-authenticatie is de manier waarop een service, voordat deze begint, bevestigt dat een binnenkomend verzoek namens een specifiek account mag handelen. De aanvrager toont de credential, de service controleert deze en geeft na verificatie een antwoord. 

Simpel gezegd beantwoordt het de vraag: is dit verzoek gemachtigd om namens dit account te handelen? Dit proces verschilt van API-autorisatie, die bepaalt wat een geauthenticeerd verzoek binnen je systeem mag doen.

Wat is sleutelbeheer?

Sleutelbeheer verwijst naar de bredere set werkwijzen waarmee je een API-sleutel gedurende zijn levenscyclus beheert. Het bepaalt hoe je sleutels maakt, opslaat, gebruikt, roteert en toegang intrekt. Deze systemen beschermen een API-sleutel van begin tot eind. 

Met strikte systemen voor sleutelbeheer kun je lekkende sleutels voorkomen en het risico verkleinen dat ze openbaar toegankelijk worden. 

Waarom beveiliging van API-sleutels belangrijk is: het dreigingsmodel

Nu authenticatie en sleutelbeheer zijn gedefinieerd, is het belangrijk om precies te zijn over wat er misgaat wanneer een sleutel verkeerd wordt behandeld. Door eerst het dreigingsmodel te bekijken, heeft elke werkwijze die we hierna behandelen een duidelijk doel: elk ervan verkleint de kans dat een sleutel lekt of de schade wanneer dit gebeurt.

ElevenAPI authenticeert via één mechanisme met een geheim: de header xi-api-key. Iedereen die de sleutel bezit, is geautoriseerd en het verzoek zelf heeft geen tweede factor.

Met je sleutel kunnen anderen je credits besteden. Text to Speech, Speech to Text, muziek en geluidseffecten worden allemaal op basis van gebruik afgerekend, en een aanvaller met een geldige sleutel kan blijven genereren totdat je quotum of saldo op is.

Ze kunnen op schaal genereren, en ons rate-limitingmodel maakt deze situatie ernstiger dan deze op het eerste gezicht lijkt. De limiet is gebaseerd op concurrency, niet op een eenvoudig quotum voor verzoeken per minuut. Een sleutel in een abonnement met een concurrencylimiet van vijf voor een bepaalde modelfamilie kan een aanzienlijk aantal gelijktijdige generaties ondersteunen. Een aanvaller die deze limieten begrijpt, zal het misbruik parallel uitvoeren.

Ze kunnen content onder je account produceren. Alle audio die met je sleutel wordt gegenereerd, wordt aan je workspace toegeschreven. Afhankelijk van de gebruikte stemmen en inputs kan dit reputatieschade en soms juridische zorgen opleveren.

De manieren waarop sleutels uitlekken zijn alledaags en komen overeen met de oorzaken van lekken van alle andere soorten credentials:

• API-sleutels in code aan de clientzijde: Een sleutel die is meegeleverd in een browserbundle, mobiele binary of single-page app is in de praktijk openbaar. Minification is geen obfuscatie.
• API-sleutels in repositories: Hardcoded sleutels die naar Git zijn gecommit, inclusief private repo's die later openbaar worden of breed worden gekloond, en bestanden zoals .env die nooit gevolgd hadden mogen worden.
• API-sleutels in logs en traces: Requestloggers, error trackers en observabilitypipelines leggen routinematig HTTP-headers vast. Een sleutel in xi-api-key belandt in je logopslag, bij je APM-leverancier en bij iedereen met leestoegang tot een van beide.
• API-sleutels in CI en screenshots: Buildlogs, supporttickets en gedeelde terminals.

Elke sectie hieronder helpt de kans of de impact van een van deze problemen te verkleinen.

De belangrijkste regel: bewaar API-sleutels server-side

De rest van dit artikel biedt inzicht in het beperken van risico's bij API-sleutelauthenticatie en -beheer. Deze regel vormt daarvan de basis en moet je boven alles implementeren.

Omdat het mechanisme zo eenvoudig is, geldt als belangrijkste regel dat een API-sleutel met lange geldigheid alleen thuishoort op een server die je beheert. De sleutel mag nooit worden meegeleverd in een browser, mobiele app, desktopclient of ander artefact dat een gebruiker kan downloaden en inspecteren. Staat de sleutel in code aan de clientzijde, behandel hem dan alsof hij al gecompromitteerd is.

De SDK leest ELEVENLABS_API_KEY automatisch, dus de meest overzichtelijke code geeft helemaal niets door en initialiseert de client één keer.

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",
});

In productie moet de sleutel bij het starten van het proces worden geladen vanuit een secret manager (AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault of het equivalent van je platform), en niet worden ingebakken in een image of in een .env die naar de repo is gecommit.

Tokens voor eenmalig gebruik voor apps aan de clientzijde

De belangrijkste regel is absoluut, maar bij veel legitieme gebruiksscenario's moet de client zelf ElevenAPI bereiken: een browser die gestreamde Text to Speech afspeelt, een mobiele app die audio vastlegt voor transcriptie en een realtime agent die in het tabblad van de gebruiker draait. Daar mag de sleutel met lange geldigheid niet terechtkomen. De oplossing is de client een credential te geven met weinig risico bij een lek: een kort geldige token voor eenmalig gebruik.

Je server bewaart de sleutel met lange geldigheid, authenticeert en autoriseert de gebruiker met je eigen sessielogica, maakt vervolgens een kort geldige token aan en geeft alleen die aan de client. De token verloopt snel en is afgebakend tot de bewerking waarvoor deze is uitgegeven, dus een gelekte token is weinig waard en al snel niets meer. Raadpleeg de referentie voor tokens voor eenmalig gebruik voor de ondersteunde endpoints en de exacte requestvorm.

Hier volgt de essentiële logica van een broker-endpoint. Deze autoriseert de gebruiker met je eigen sessielogica en maakt vervolgens een token aan via het gedocumenteerde tokens-endpoint. Het verzoek vertrekt vanaf de server met de lang geldige xi-api-key, en alleen de resulterende kort geldige token keert terug naar de client.

// ... 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() });
});

De browser gebruikt die token vervolgens om verbinding te maken en de sleutel met lange geldigheid komt nooit op de pagina terecht.

Sleutels afbakenen volgens least privilege

Least privilege is het principe dat elke sleutel alleen de rechten mag hebben die nodig zijn voor zijn taak, en niets meer. Met ElevenAPI kun je verschillende beperkingen op basis van rechten instellen die bepalen wat een sleutel wel en niet kan doen.

Eén sleutel met alle rechten is het slechtste scenario voor de impact van een lek, maar ook de gemakkelijke standaardkeuze. Een betere aanpak is ervan uitgaan dat elke sleutel uiteindelijk zal lekken en ervoor zorgen dat deze dan alleen kan doen wat de taak vereist.

Begin met het beperken van de scope, waarmee je vastlegt welke API-endpoints een sleutel mag aanroepen. Een sleutel die alleen voor transcriptie wordt gebruikt, heeft geen toegang tot Text to Speech nodig; een sleutel voor een muziekfunctie hoeft geen stembeheer te kunnen gebruiken.

Daarna volgt het creditquotum. Een aangepaste creditlimiet per sleutel begrenst de financiële schade van een lek en beperkt ook ontspoorde loops in je eigen code.

IP-whitelisting gaat nog verder. Je kunt een sleutel beperken tot specifieke IP-adressen of CIDR-bereiken; verzoeken vanaf IP's die niet op de whitelist staan, worden afgewezen met een 403. Dit is een Enterprise-functie die momenteel als preview beschikbaar is via je accountmanager.

Deel ten slotte geen sleutel tussen development, staging en productie. Geef per omgeving een aparte sleutel uit, elk met een eigen scope en quotum. Sleutels per omgeving houden een lek op de laptop van een ontwikkelaar weg van productiecredits, laten je één omgeving roteren zonder de andere te verstoren en maken gebruikslogs beter interpreteerbaar, omdat verkeer al naar herkomst is gesegmenteerd.

Rotatie van API-sleutels

Sleutelrotatie is het regelmatig vervangen van een sleutel door een nieuwe. Je kunt dit ook doen zodra je een inbreuk of blootstelling vermoedt.

Volgens een schema verkleint rotatie ook de periode waarin een onopgemerkt lek kan worden misbruikt. Rotatie verloopt alleen probleemloos als je code ervoor is ontworpen, dus ontwerp voor rotatie voordat je die nodig hebt.

De basistechniek is overlappende sleutels, waarmee je zonder downtime kunt overschakelen:

1. Genereer een nieuwe API-sleutel: Maak naast de bestaande sleutel een nieuwe sleutel aan met dezelfde scope, hetzelfde quotum en dezelfde IP-beperkingen. Beide zijn nu geldig.
2. Werk de sleutel bij: Rol de nieuwe sleutel uit door het secret in je secret manager bij te werken en instances deze te laten ophalen (via een herstart, opnieuw lezen of een refresh van de secret manager, afhankelijk van je configuratie).
3. Bevestig het verkeer: Controleer of verkeer via de nieuwe sleutel loopt. Bekijk het gebruik om te bevestigen dat de oude sleutel niet meer wordt gebruikt.
4. Verwijder sleuteltoegang: Trek de oude sleutel in zodra deze gedurende een veilige periode geen verkeer meer toont.

Omdat beide sleutels tijdens de overlap geldig zijn, is er nooit een moment waarop verzoeken falen door een ontbrekende credential. Het overlapvenster heeft nog een voordeel: een verkeerd geconfigureerde instance verraadt zichzelf door de oude sleutel te blijven gebruiken, zodat je deze kunt vinden voordat je die sleutel uitschakelt.

Om de overlap probleemloos te laten verlopen, structureer je code zo dat rotatie een configuratiewijziging is en nooit een codewijziging. Lees de sleutel op één plek in, waar deze kan worden vernieuwd, en laat één schakelaar bepalen welk secret actief is.

// 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;
}

Tijdens een overlap houd je zowel PRIMARY als SECONDARY gevuld en wijzig je ELEVENLABS_KEY_ACTIVE. De applicatiecode verandert nooit.

Als ritme is een standaardrotatie elke 90 dagen een redelijk uitgangspunt voor backendsleutels, vaker voor sleutels met hoge waarde of brede toegang en onmiddellijk bij elke blootstelling. Je kunt dit automatiseren met een geplande job die sleutels maakt, uitrolt, controleert en intrekt, waardoor rotatie van een gebeurtenis een achtergrondproces wordt.

Toegangscontroles en rechten voor workspaces

Terwijl scope en rotatie individuele sleutels beveiligen, bepalen workspacecontroles wie deze überhaupt kan maken. Zo kun je organisatorisch beleid vastleggen en volgen, wat al je toekomstige werkwijzen voor sleutelbeheer beïnvloedt.

Begin met het scheiden van credentials voor mensen en machines. Mensen loggen in op het dashboard met hun eigen accounts en rechten; services authenticeren met sleutels of, nog beter, serviceaccounts. Laat een service niet draaien op een sleutel die is gemaakt vanuit de persoonlijke toegang van één persoon, en laat mensen niet één machinesleutel delen. De reden is offboarding: wanneer iemand vertrekt of een service wordt uitgefaseerd, wil je precies de juiste credential kunnen intrekken zonder nevenschade.

Serviceaccounts dienen hetzelfde doel. Ze geven machineworkloads een identiteit die niet aan een persoon is gekoppeld, met een eigen scope, waardoor je audittrail betrouwbaar blijft.

Koppel toegang vervolgens aan rollen in plaats van deze persoon voor persoon toe te wijzen. Workspaces ondersteunen hiervoor groeps- en ledenrechten. Verleen de minimale rechten waarmee elke groep zijn werk kan doen, controleer het lidmaatschap regelmatig en streef naar een inrichting waarin geen enkele credential, menselijk of machinaal, meer kan doen dan de bijbehorende rol vereist.

Audit en detectie

In de vorige fasen hebben we beschreven hoe je de schade van een lek beperkt. In deze fase beschrijven we hoe je vaststelt of er überhaupt een lek is geweest. Goede detectie berust op drie gewoonten. 

De eerste is vastleggen welke sleutel (aan de hand van de identifier, nooit de geheime waarde) welke klasse verzoeken verwerkte, vanwaar en in welk volume. Verwijder de header xi-api-key uit elke logging- en tracinglaag. Een redactieregel in je HTTP-middleware en APM-configuratie voorkomt de meest voorkomende manier waarop sleutels überhaupt in logopslag terechtkomen.

De tweede is creditverbruik controleren op anomalieën. Volg het creditverbruik per sleutel in de tijd en waarschuw bij afwijkingen van de basislijn: een plotselinge piek, generaties op ongebruikelijke tijden of een sleutel die inactief zou moeten zijn maar plotseling actief wordt.

De derde is het bekijken van de concurrencyheaders. In elke response sturen we het huidige en maximale aantal gelijktijdige verzoeken mee in de headers current-concurrent-requests en maximum-concurrent-requests. Deze geven aan hoeveel capaciteit je nog hebt, en een aanhoudende maximale belasting die je niet zelf hebt veroorzaakt, is een sterk signaal van misbruik. Via het onbewerkte HTTP-endpoint zijn de responseheaders rechtstreeks beschikbaar:

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.

Deze signalen moeten alerts activeren. Een dashboard waar niemand naar kijkt, biedt geen detectie. Koppel signalen voor creditpieken en verzadigde concurrency aan hetzelfde alertingpad dat je voor storingen gebruikt, met een duidelijk aangewezen eigenaar.

Incidentrespons

Zelfs met de best mogelijke beveiligings- en monitoringsystemen moet je ervan uitgaan dat een sleutel uiteindelijk lekt. Door daarop vooruit te plannen met een lijst stappen om schade te beperken, krijg je een responsroute die tijd bespaart en de impact verkleint.

Hier is een vooraf gedefinieerd stappenplan voor incidentrespons bij blootstelling van een API-sleutel:

1. Trek de gelekte sleutel onmiddellijk in: Wacht niet tot je de volledige omvang begrijpt. Een ingetrokken sleutel kan niet genereren, en je kunt altijd een vervangende sleutel uitgeven. Dit is de actie met de hoogste waarde.
2. Roteer naar een nieuwe sleutel: Als de gelekte sleutel productieverkeer verwerkte, gebruik dan de overlapprocedure omgekeerd: maak een nieuwe sleutel aan, leid het verkeer om en bevestig vervolgens dat de gelekte sleutel niet meer werkt. Omdat je code de sleutel uit de configuratie leest, is dit een configuratiewijziging en geen codewijziging.
3. Beoordeel de impact aan de hand van gebruikslogs: Kwantificeer de schade zodra het lek is ingedamd. Hoe lang was de sleutel geldig en blootgesteld? Welke credits zijn in die periode verbruikt, en past het patroon bij legitiem verkeer of misbruik? Welke endpoints zijn aangeroepen?
4. Roteer afhankelijke secrets: Een sleutel lekt zelden alleen. Als deze in een repo, logopslag of CI-pipeline is blootgesteld, ga er dan van uit dat aangrenzende secrets op dezelfde plek ook zijn blootgesteld en roteer die eveneens.
5. Sluit het lekpad: Zoek uit hoe de sleutel is ontsnapt en los dat op, anders gebeurt het opnieuw: voeg het bestand toe aan .gitignore en verwijder de geschiedenis, voeg headerredactie toe aan de logger, verplaats het secret uit het buildartefact en beperk de toegang tot het CI-systeem.
6. Schrijf de post-mortem: Documenteer de tijdlijn, de impact, de hoofdoorzaak en de toegevoegde concrete controles (strakkere scope, IP-whitelisting, een secretscanner in CI en een hogere rotatiefrequentie).

Door deze stappen te volgen, beschik je over een vast proces voor rampscenario's rond blootstelling van je API. 

Compliance: SOC 2, HIPAA en gegevensbewaring

Authenticatie is één onderdeel van een bredere compliancebeoordeling. Wees zorgvuldig met wat hier wel en niet kan worden beweerd. Zie het volgende als feitelijke uitgangspunten, niet als een beoordeling voor jouw gebruiksscenario.

ElevenLabs is SOC 2-compliant. Voor in aanmerking komende abonnementen en gebruiksscenario's zijn HIPAA-compliance en modi zonder gegevensbewaring beschikbaar. Geen gegevensbewaring betekent dat requestcontent na verwerking niet wordt opgeslagen, wat belangrijk is wanneer je inputs of gegenereerde audio gevoelig zijn.

Of een bepaalde modus van toepassing is, hangt af van je abonnement, je configuratie en de details van wat je verwerkt. Bevestig voor je erop vertrouwt of je account in aanmerking komt en wat de exacte voorwaarden zijn, en combineer dit met de hierboven beschreven toegangscontroles. Compliancecertificeringen bepalen hoe het platform je gegevens verwerkt; sleutelbeheer bepaalt wie namens jou kan handelen, en dat deel ligt bij jou.

Hoe goede beveiliging van API-sleutels eruitziet

Sleutels die alleen server-side worden gebruikt, verwijderen het grootste lekoppervlak. Tokens voor eenmalig gebruik breiden die garantie uit naar clients die onze API echt moeten bereiken. Scope en scheiding per omgeving begrenzen de schade van elk lek. Rotatie in de configuratie maakt herstel routinematig in plaats van risicovol. Workspacecontroles houden menselijke en machine-identiteiten gescheiden. Audits maken van misbruik een alert in plaats van een verrassing op je factuur. Een geschreven runbook maakt van een incident een procedure.

Dit is dezelfde credentialhygiëne die elk waardevol secret beschermt, toegepast op een sleutel waarvan de bijzondere waarde is dat deze geld uitgeeft en audio op schaal genereert.

Wanneer je klaar bent om dit te koppelen aan de werkelijke requestvormen, bevatten de authenticatiereferentie en de referentie voor tokens voor eenmalig gebruik de actuele lijst met ondersteunde endpoints. Om het concurrencymodel te begrijpen dat je monitoring moet volgen, zijn de modellenreferentie en de API-quickstart de juiste volgende lectuur.

Beveilig je ElevenAPI-integratie

Sterke API-authenticatie is een fundamentele controle waarop vele andere beveiligingspraktijken voortbouwen. Maatregelen zoals alleen server-side sleutels gebruiken, tokens voor eenmalig gebruik voor clients inzetten, scopes volgens least privilege beperken en rotatie opnemen in sleutelbeheer helpen risico's op schaal te voorkomen.

Raadpleeg voor meer informatie over ondersteunde endpoints en de exacte headerindeling de ElevenAPI-documentatie. Ben je klaar om aan de slag te gaan, vraag dan een API-sleutel aan bij ElevenLabs en begin vandaag nog met bouwen. 

Veelgestelde vragen over API-authenticatie en sleutelbeheer