Claves de API

Descripción general

Las claves de API autentican tus solicitudes a la API de ElevenLabs y registran el uso en relación con la cuota de tu espacio de trabajo. Hay dos tipos:

• Las claves de API de usuario pertenecen a un usuario concreto y heredan el acceso de este a los recursos del espacio de trabajo. Son adecuadas para desarrollo personal y scripts, y pueden tener una caducidad para que dejen de funcionar automáticamente tras un periodo determinado. Como están vinculadas a una persona, una clave de API de usuario se ve afectada si cambia el acceso de ese usuario o si abandona el espacio de trabajo. Para crear claves de API personales necesitas un Asiento completo.
• Las claves de API de cuentas de servicio pertenecen a una cuenta de servicio en lugar de a una persona, por lo que siguen funcionando independientemente de los cambios en las membresías individuales. Se recomiendan para sistemas backend, automatización y cargas de trabajo de producción. Las cuentas de servicio están disponibles para clientes con varios asientos y las gestionan los administradores del espacio de trabajo.

Tu clave de API es secreta. No la compartas con otras personas ni la expongas en código del lado del cliente (navegadores, apps). Para saber cómo enviar tu clave con una solicitud, consulta la referencia de Autenticación de la API.

Puedes restringir ambos tipos de claves de varias formas:

1. Restricción de alcance: limita a qué rutas de API puede acceder la clave.
2. Cuota de créditos: establece un límite de créditos personalizado para controlar el uso.
3. Lista de IP permitidas: restringe la clave a direcciones IP o rangos CIDR específicos. Consulta Lista de IP permitidas.

Claves de API de usuario con caducidad

Puedes establecer una fecha de caducidad para las claves de API de usuario, de modo que dejen de funcionar automáticamente tras un periodo determinado. Esto limita el periodo durante el que se puede utilizar una clave filtrada u olvidada y se adapta a la naturaleza temporal de las claves vinculadas a una persona.

Establece una caducidad al crear o editar una clave desde tu configuración de claves de API personales. Usa el selector Caduca después de para elegir un ajuste predefinido de entre 15 minutos y 30 días, o déjalo en Nunca (el valor predeterminado). La columna Caduca muestra cuándo vencerá cada clave.

Cuando una clave supera su fecha de caducidad, deja de autenticar y las solicitudes realizadas con ella se rechazan con un error 401. Puedes ampliar o eliminar la caducidad editando la clave antes de que venza; de lo contrario, rótala para obtener una nueva.

Rotación de claves de API

La rotación sigue el mismo patrón en ambos casos: crea una clave nueva, cambia tus aplicaciones para que la usen y, después, elimina la clave antigua.

Las claves de API de usuario se rotan desde el panel de control. Abre tu configuración de claves de API personales, crea una clave nueva y elimina la antigua cuando hayas realizado el cambio.

Las claves de API de cuentas de servicio se pueden rotar desde el panel de control o mediante la API:

• En el panel de control, haz clic en el icono de tu perfil en la esquina superior derecha, selecciona Configuración del espacio de trabajo y abre la pestaña Cuentas de servicio. Crea una clave nueva para la misma cuenta de servicio y elimina la antigua cuando hayas realizado el cambio.
• Mediante la API, crea una clave nueva para la misma cuenta de servicio y, después, elimina la antigua.

Lista de IP permitidas

Puedes restringir una clave de API para que solo funcione desde direcciones IP o rangos CIDR específicos. Las solicitudes realizadas desde cualquier otra IP se rechazarán con un error 403.

Formatos compatibles

• Direcciones IPv4 individuales (p. ej., 203.0.113.10)
• Direcciones IPv6 individuales (p. ej., 2001:db8::1)
• Rangos CIDR (p. ej., 203.0.113.0/24)

Puedes añadir entre 1 y 100 entradas por clave de API. Las direcciones IP sin prefijo se normalizan automáticamente a /32 (IPv4) o /128 (IPv6).

Detección de claves filtradas

ElevenLabs participa en el programa de socios de escaneo de secretos de GitHub. Si se confirma una clave de API de ElevenLabs en un repositorio público de GitHub, GitHub notifica a ElevenLabs y la clave se desactiva automáticamente para evitar usos no autorizados.

Una clave desactivada de esta manera muestra exposed_publicly como disable_reason. Para restaurar el acceso, rota la clave y actualiza tus aplicaciones para usar la nueva.

Desactivar una clave por cuenta propia

Si crees que una clave se ha visto comprometida, su titular puede desactivarla directamente mediante la ruta Desactivar clave de API. Llámala con el parámetro de consulta api_key_name=self, que es necesario como confirmación explícita de que quieres desactivar la clave utilizada para autenticar la solicitud.

Controlar quién puede desactivar claves

La configuración third_party_disable_allowed controla si una clave puede ser desactivada por su titular, ya sea mediante la ruta de autodesactivación o automáticamente si se filtra públicamente. De forma predeterminada, está activada en los planes que no son Enterprise y desactivada en los planes Enterprise.

Por clave: establece third_party_disable_allowed al crear o actualizar una clave de API de cuenta de servicio. Omítelo para usar el valor predeterminado del espacio de trabajo, o pasa clear al actualizar para restablecer una clave individual al valor predeterminado del espacio de trabajo.

Para todo el espacio de trabajo: los administradores del espacio de trabajo pueden anular la configuración de todas las claves a la vez mediante la ruta Establecer la política de desactivación por terceros del espacio de trabajo:

• true permite que el titular desactive todas las claves del espacio de trabajo.
• false lo prohíbe para todas las claves.
• null elimina la anulación para todo el espacio de trabajo, por lo que vuelven a aplicarse el valor de cada clave y el valor predeterminado del plan.