Autenticación de API y gestión de claves para ElevenAPI

La autenticación de API es el proceso por el que un servicio verifica que una solicitud entrante tiene permiso para actuar sobre una cuenta. Por ejemplo, con ElevenAPI, las credenciales de API autorizan solicitudes que consumen créditos, generan voz y música a escala y, en algunos casos, acceden a audio sensible.

Si una clave se filtra, puede costarte dinero y usarse para generar contenido desde tu cuenta. También puede dar acceso excesivo a tus plataformas, lo que puede provocar fugas de datos y otros riesgos. Ya en 2020, más del 90% de desarrolladores usaban APIs en al menos un proceso diario. Ahora, con el auge de los MCP (model context protocols) y el uso de IA, las APIs están en todas partes.

En este artículo verás cómo autenticar APIs correctamente y cómo gestionar claves durante todo su ciclo de vida: definir permisos, rotar, controles organizativos, auditoría y respuesta ante incidentes. Así podrás configurar la autenticación y gestión de claves de API en tu equipo. Mientras lees, ten a mano la referencia de autenticación y la referencia de tokens de un solo uso.

Resumen rápido

• ElevenAPI autentica cada solicitud mediante un único secreto, la cabecera xi-api-key, lo que significa que cualquiera que tenga una clave puede gastar créditos y generar audio en la cuenta.
• Nunca incluyas una clave de API de larga duración en el navegador, app móvil o cualquier otro archivo que un usuario pueda inspeccionar. Guárdalas solo en un servidor que controles.
• Si necesitas usar la API desde el lado del cliente, autentica siempre con tokens de un solo uso y corta duración generados en el servidor, nunca con la clave de larga duración.
• Puedes reducir el impacto de una filtración limitando los permisos de las claves, separando claves por entorno y rotándolas periódicamente.
• La auditoría y la detección de anomalías ayudan a prevenir filtraciones y sorpresas.

¿Qué es la autenticación de API?

La autenticación de API es el proceso por el que un servicio confirma que una solicitud entrante tiene permiso para actuar sobre una cuenta concreta antes de empezar a trabajar. El solicitante presenta la credencial, el servicio la verifica y, si es válida, responde.

En resumen, responde a: ¿Esta solicitud está autorizada para actuar en esta cuenta? Es importante no confundirlo con la autorización de API, que define qué puede hacer una solicitud autenticada dentro de tu sistema.

¿Qué es la gestión de claves?

La gestión de claves es el conjunto de prácticas para controlar una clave de API durante todo su ciclo de vida. Incluye cómo crearla, almacenarla, usarla, rotarla y revocar el acceso. Todo esto garantiza la seguridad de la clave de principio a fin.

Con sistemas rigurosos de gestión de claves puedes evitar filtraciones y reducir el riesgo de que se hagan públicas.

Por qué importa la seguridad de las claves de API: el modelo de amenazas

Ahora que ya sabes qué es la autenticación y la gestión de claves, es importante entender qué puede fallar si una clave se gestiona mal. Analizar primero el modelo de amenazas ayuda a que cada práctica que veamos tenga un propósito claro: reducir la probabilidad de filtración o el daño si ocurre.

ElevenAPI autentica mediante un único mecanismo: la cabecera xi-api-key. Cualquiera que tenga la clave está autorizado y no hay un segundo factor en la solicitud.

Con tu clave pueden gastar tus créditos. Texto a Voz, Voz a Texto, música y efectos de sonido consumen créditos, y un atacante con una clave válida puede generar contenido hasta agotar tu cuota o saldo.

Pueden generar a gran escala, y nuestro modelo de limitación por concurrencia hace que esto sea más grave de lo que parece. El límite depende de la concurrencia, no de un simple número de solicitudes por minuto. Una clave con un límite de concurrencia de cinco puede mantener varias generaciones simultáneas, y un atacante que entienda estos límites puede abusar en paralelo.

Pueden generar contenido desde tu cuenta. Todo el audio generado con tu clave se atribuye a tu espacio de trabajo y, según las voces y entradas usadas, puede ser un problema reputacional o incluso legal.

Las formas en que se filtran las claves son habituales y son los mismos fallos que afectan a cualquier otra credencial:

• Claves de API en código del lado del cliente: Una clave incluida en un bundle de navegador, binario móvil o app de una sola página es, en la práctica, pública. Minificar no es ofuscar.
• Claves de API en repositorios: Claves hardcodeadas en Git, incluso en repos privados que luego se hacen públicos o se clonan, y en archivos como .env que nunca debieron subirse.
• Claves de API en logs y trazas: Los logs de solicitudes, rastreadores de errores y sistemas de observabilidad suelen capturar cabeceras HTTP. Una clave en xi-api-key acaba en tu sistema de logs, en tu proveedor de APM y en manos de cualquiera con acceso de lectura.
• Claves de API en CI y capturas de pantalla: Logs de builds, tickets de soporte y terminales compartidas.

Cada sección a continuación ayuda a reducir la probabilidad o el impacto de alguna de estas situaciones.

La regla de oro: mantén las claves de API solo en el servidor

Todo lo demás en este artículo ayuda a reducir riesgos en la autenticación y gestión de claves de API. Pero esta regla es la base y lo primero que debes aplicar.

Como el mecanismo es tan simple, la regla de oro es que una clave de API de larga duración solo debe estar en un servidor que controles. Nunca debe incluirse en un navegador, app móvil, cliente de escritorio ni en ningún archivo que un usuario pueda descargar e inspeccionar. Si la clave está en código del lado del cliente, considérala ya comprometida.

El SDK lee automáticamente ELEVENLABS_API_KEY, así que el código más limpio no pasa nada y solo inicializa el cliente una vez.

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

En producción, la clave debe obtenerse de un gestor de secretos (AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault o el equivalente de tu plataforma) al iniciar el proceso, nunca incrustada en una imagen ni en un .env subido al repo.

Tokens de un solo uso para apps del lado del cliente

La regla de oro es absoluta, pero hay casos legítimos en los que el cliente necesita acceder a ElevenAPI: un navegador que reproduce Texto a Voz en streaming, una app móvil que graba audio para transcribir o un agente en tiempo real en la pestaña del usuario. La clave de larga duración no puede ir ahí. La solución es dar al cliente una credencial de bajo riesgo si se filtra: un token de un solo uso y corta duración.

Tu servidor guarda la clave de larga duración, autentica y autoriza al usuario con tu lógica de sesión y luego genera un token de corta duración que solo entrega al cliente. El token caduca rápido y solo sirve para la operación concreta, así que si se filtra vale poco y pronto nada. Consulta la referencia de tokens de un solo uso para ver las rutas de API soportadas y el formato exacto de la solicitud.

Aquí tienes la lógica esencial de una ruta de broker. Autoriza al usuario con tu lógica de sesión y luego genera un token usando la ruta documentada de tokens. La solicitud sale con la xi-api-key de larga duración desde el servidor y solo el token de corta duración llega al cliente.

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

El navegador usa ese token para conectarse y la clave de larga duración nunca entra en la página.

Limitar permisos de las claves (least privilege)

El principio de mínimo privilegio significa que cada clave solo debe tener los permisos necesarios para su función, y nada más. ElevenAPI te permite aplicar varias restricciones por permisos para limitar lo que puede hacer cada clave.

Una única clave con todos los permisos es el peor caso posible y, además, el más fácil por defecto. Es mejor asumir que cualquier clave acabará filtrándose y asegurarte de que, si ocurre, solo pueda hacer lo imprescindible.

Empieza limitando el alcance, que restringe a qué rutas de API puede acceder una clave. Una clave solo para transcripción no necesita acceso a Texto a Voz; una clave para música no necesita gestionar voces.

Después, limita la cuota de créditos. Asignar un límite personalizado por clave reduce el daño económico de una filtración y también evita bucles descontrolados en tu propio código.

La lista blanca de IPs va un paso más allá. Puedes restringir una clave a IPs o rangos CIDR concretos; las solicitudes desde IPs no permitidas se rechazan con un 403. Es una función Enterprise en vista previa, disponible a través de tu account manager.

Por último, no compartas una clave entre desarrollo, staging y producción. Usa una clave distinta por entorno, cada una con su propio alcance y cuota. Así, una filtración en el portátil de un desarrollador no afecta a los créditos de producción, puedes rotar un entorno sin tocar los demás y los logs de uso son más claros porque el tráfico ya está segmentado por origen.

Rotación de claves de API

La rotación de claves consiste en reemplazar una clave por otra nueva de forma periódica. También es lo que debes hacer si sospechas una filtración o exposición.

Si rotas regularmente, reduces la ventana en la que una filtración no detectada puede ser explotada. La rotación solo es sencilla si tu código está preparado para ello, así que diseña pensando en la rotación antes de necesitarla.

La técnica clave es solapar claves, lo que permite cambiar sin tiempo de inactividad:

1. Genera una nueva clave de API: Crea una clave nueva junto a la existente, con el mismo alcance, cuota y restricciones de IP. Ambas son válidas.
2. Actualiza la clave: Despliega la nueva clave actualizando el secreto en tu gestor de secretos y dejando que las instancias la recojan (reinicio, recarga o refresco del gestor de secretos, según tu sistema).
3. Confirma el tráfico: Verifica que el tráfico pasa por la nueva clave. Comprueba que la antigua deja de usarse.
4. Elimina el acceso de la clave: Revoca la clave antigua cuando no tenga tráfico durante un tiempo prudencial.

Como ambas claves son válidas durante el solape, nunca hay un momento en que las solicitudes fallen por falta de credencial. Además, si alguna instancia está mal configurada, seguirá usando la clave antigua y podrás detectarla antes de revocarla.

Para que la rotación sea transparente, estructura tu código para que rotar sea solo un cambio de configuración, nunca de código. Lee la clave de un solo sitio, en un punto donde pueda refrescarse, y usa un único switch para decidir qué secreto está activo.

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

Durante el solape, mantén PRIMARY y SECONDARY y cambia ELEVENLABS_KEY_ACTIVE. El código de la aplicación no cambia.

Como referencia, una rotación rutinaria cada 90 días es un buen punto de partida para claves backend, más frecuente para claves de alto valor o muy usadas, e inmediata ante cualquier exposición. Puedes automatizarlo con un job programado que cree, cambie, verifique y revoque, convirtiendo la rotación en un proceso de fondo.

Controles de acceso y permisos en el espacio de trabajo

Mientras que el alcance y la rotación protegen claves individuales, los controles del espacio de trabajo determinan quién puede crearlas. Aquí defines y aplicas la política organizativa, que influirá en toda tu gestión de claves.

Empieza separando credenciales humanas y de máquina. Las personas acceden al panel con sus cuentas y permisos; los servicios se autentican con claves o, mejor, cuentas de servicio. No dejes que un servicio use una clave creada desde el acceso personal de alguien, ni que varias personas compartan una clave de máquina. Así, cuando alguien se va o un servicio se retira, puedes revocar solo la credencial correcta sin afectar a otras.

Las cuentas de servicio cumplen el mismo objetivo. Dan identidad a procesos automáticos sin depender de una persona, con su propio alcance, y mantienen la trazabilidad de auditoría.

Después, asigna permisos por roles, no por personas una a una. Los espacios de trabajo permiten permisos por grupo y miembro para esto. Da el mínimo privilegio necesario a cada grupo, revisa la membresía periódicamente y busca que ninguna credencial, humana o de máquina, pueda hacer más de lo que su rol requiere.

Auditoría y detección

Hasta aquí hemos visto cómo reducir el daño de una filtración. Ahora toca ver cómo detectar si ha ocurrido. Una buena detección se basa en tres hábitos:

El primero es registrar qué clave (por identificador, nunca el valor secreto) ha servido cada tipo de solicitud, desde dónde y con qué volumen. Elimina la cabecera xi-api-key de todos los logs y trazas. Una regla de redacción en tu middleware HTTP y en la configuración de APM evita la forma más común de que las claves acaben en los logs.

El segundo es monitorizar el consumo de créditos para detectar anomalías. Haz seguimiento del gasto de créditos por clave y alerta ante desviaciones: un pico repentino, generación en horarios inusuales o una clave que debería estar inactiva y de repente se activa.

El tercero es vigilar las cabeceras de concurrencia. Devolvemos el número actual y máximo de solicitudes concurrentes en las cabeceras current-concurrent-requests y maximum-concurrent-requests. Así sabes el margen que tienes, y si ves el máximo sostenido sin haberlo provocado, es señal clara de abuso. Usar la ruta HTTP directa expone estas cabeceras:

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.

Esto debe generar alertas. Un panel que nadie mira no sirve para detectar nada. Integra las alertas de picos de créditos y saturación de concurrencia en el mismo canal que usas para caídas, con un responsable claro.

Respuesta ante incidentes

Incluso con los mejores sistemas de seguridad y monitorización, debes asumir que alguna clave acabará filtrándose. Tener un plan de pasos para limitar el daño te da una hoja de ruta que ahorra tiempo y reduce el impacto.

Aquí tienes un protocolo de respuesta ante incidentes por filtración de clave de API:

1. Revoca la clave filtrada de inmediato: No esperes a entender todo el alcance. Una clave revocada no puede generar nada y siempre puedes crear una nueva. Es la acción más importante.
2. Rota a una clave nueva: Si la clave filtrada estaba en producción, usa el proceso de solape al revés: crea una nueva, cambia el tráfico y confirma que la filtrada ya no se usa. Como tu código lee la clave de la configuración, solo tienes que cambiar la config, no el código.
3. Evalúa el alcance del daño en los logs de uso: Una vez contenida la filtración, cuantifícala. ¿Cuánto tiempo estuvo la clave expuesta? ¿Cuántos créditos se gastaron y el patrón coincide con uso legítimo o abuso? ¿A qué rutas accedió?
4. Rota secretos dependientes: Una clave rara vez se filtra sola. Si apareció en un repo, log o CI, asume que los secretos cercanos también están expuestos y rótalos.
5. Cierra la vía de filtración: Encuentra cómo se filtró la clave y arréglalo o volverá a pasar: añade el archivo a .gitignore y borra el historial, añade redacción de cabeceras al logger, mueve el secreto fuera del artefacto de build y restringe el acceso al sistema de CI.
6. Escribe el post-mortem: Documenta la cronología, el alcance del daño, la causa raíz y los controles añadidos (restricción de alcance, lista blanca de IPs, escáner de secretos en CI y mayor frecuencia de rotación).

Siguiendo estos pasos tendrás un proceso claro para actuar ante filtraciones de API.

Cumplimiento normativo: SOC 2, HIPAA y retención de datos

La autenticación es solo un aspecto dentro de una evaluación de cumplimiento más amplia, y conviene ser preciso con lo que se puede o no afirmar aquí. Toma lo siguiente como punto de partida, no como decisión final para tu caso.

ElevenLabs es compatible con SOC 2. Para planes y casos de uso elegibles, hay opciones de cumplimiento HIPAA y modos sin retención de datos. Sin retención significa que el contenido de la solicitud no se almacena tras el procesamiento, lo que es importante si tus entradas o el audio generado son sensibles.

Si se aplica un modo u otro depende de tu plan, configuración y de lo que proceses. Confirma la elegibilidad y los términos exactos para tu cuenta antes de confiar en ellos, y combínalos con los controles de acceso descritos arriba. Las certificaciones de cumplimiento regulan cómo la plataforma trata tus datos; la gestión de claves determina quién puede actuar en tu nombre, y esa parte es tuya.

Cómo es una buena seguridad de claves de API

Las claves solo en el servidor eliminan la mayor superficie de filtración. Los tokens de un solo uso extienden esa garantía a los clientes que realmente necesitan acceder a nuestra API. Limitar el alcance y separar por entorno reduce el daño de cualquier filtración. La rotación integrada en la configuración hace que recuperarse sea rutina y no un riesgo. Los controles del espacio de trabajo separan identidades humanas y de máquina. La auditoría convierte el abuso en una alerta y no en una sorpresa en tu factura. Un protocolo escrito convierte un incidente en un procedimiento.

Es la misma higiene de credenciales que protege cualquier secreto valioso, aplicada a una clave cuyo valor es que gasta dinero y genera audio a escala.

Cuando quieras implementar esto con las rutas reales, la referencia de autenticación y la de tokens de un solo uso tienen la lista actual de rutas soportadas. Para entender el modelo de concurrencia que debes monitorizar, consulta la referencia de modelos y el inicio rápido de la API.

Protege tu integración con ElevenAPI

Una autenticación de API robusta es la base sobre la que se construyen muchas otras prácticas de seguridad. Medidas como usar claves solo en el servidor, tokens de un solo uso para clientes, mínimo privilegio y rotación integrada en la gestión de claves ayudan a prevenir riesgos a gran escala.

Para más información sobre rutas soportadas y el formato exacto de la cabecera, consulta la documentación de ElevenAPI. Si quieres empezar, solicita una clave de API de ElevenLabs y empieza a crear hoy mismo.

Preguntas frecuentes sobre autenticación de API y gestión de claves