Chaves de API

Visão geral

As chaves de API autenticam suas solicitações à API do ElevenLabs e acompanham o uso em relação à cota do seu workspace. Há dois tipos:

• As chaves de API de usuário pertencem a um usuário individual e herdam o acesso desse usuário aos recursos do workspace. Elas são adequadas para desenvolvimento pessoal e scripts, e podem receber uma data de expiração para deixar de funcionar automaticamente após um período definido. Como estão vinculadas a uma pessoa, uma chave de API de usuário é afetada se o acesso desse usuário mudar ou se ele sair do workspace. A criação de chaves de API pessoais exige um Assento completo.
• As chaves de API de conta de serviço pertencem a uma conta de serviço, e não a uma pessoa, portanto, continuam funcionando independentemente de mudanças na associação individual. Elas são recomendadas para sistemas de backend, automação e cargas de trabalho de produção. As contas de serviço estão disponíveis para clientes com vários assentos e são gerenciadas pelos administradores do workspace.

Sua chave de API é secreta. Não a compartilhe com outras pessoas nem a exponha em código do lado do cliente (navegadores, apps). Para saber como enviar sua chave em uma solicitação, consulte a referência de Autenticação da API.

Os dois tipos de chave podem ser restringidos de várias formas:

1. Restrição de escopo: limita os endpoints da API que a chave pode acessar.
2. Cota de créditos: define um limite de créditos personalizado para controlar o uso.
3. Lista de IPs permitidos: restringe a chave a endereços IP ou intervalos CIDR específicos. Consulte Lista de IPs permitidos.

Chaves de API de usuário com expiração

As chaves de API de usuário podem receber uma data de expiração para deixar de funcionar automaticamente após um período definido. Isso limita a janela em que uma chave vazada ou esquecida pode ser usada e é adequado à natureza temporária das chaves vinculadas a uma pessoa.

Defina uma expiração ao criar ou editar uma chave nas configurações de suas chaves de API pessoais. Use o seletor Expirar após para escolher uma opção predefinida entre 15 minutos e 30 dias ou deixe como Nunca (o padrão). A coluna Expira em mostra quando cada chave expirará.

Quando uma chave ultrapassa sua data de expiração, ela deixa de autenticar e as solicitações feitas com ela são rejeitadas com um erro 401. Você pode estender ou remover a expiração editando a chave antes que ela expire; caso contrário, altere para uma nova chave.

Alternando chaves de API

A alternância segue o mesmo padrão nos dois casos: crie uma nova chave, altere suas aplicações para usá-la e, em seguida, exclua a chave antiga.

As chaves de API de usuário são alternadas no painel. Abra as configurações de suas chaves de API pessoais, crie uma nova chave e exclua a antiga quando concluir a alteração.

As chaves de API de conta de serviço podem ser alternadas no painel ou pela API:

• No painel, clique no ícone do seu perfil no canto superior direito, selecione Configurações do workspace e abra a aba Contas de serviço. Crie uma nova chave para a mesma conta de serviço e exclua a antiga quando concluir a alteração.
• Pela API, crie uma nova chave para a mesma conta de serviço e depois exclua a antiga.

Lista de IPs permitidos

Você pode restringir uma chave de API para que ela funcione apenas a partir de endereços IP ou intervalos CIDR específicos. Solicitações feitas de qualquer outro IP serão rejeitadas com um erro 403.

Formatos compatíveis

• Endereços IPv4 individuais (por exemplo, 203.0.113.10)
• Endereços IPv6 individuais (por exemplo, 2001:db8::1)
• Intervalos CIDR (por exemplo, 203.0.113.0/24)

Você pode adicionar entre 1 e 100 entradas por chave de API. Endereços IP sem máscara são automaticamente normalizados para /32 (IPv4) ou /128 (IPv6).

Detectando chaves vazadas

O ElevenLabs participa do programa de parceiros de escaneamento de segredos do GitHub. Se uma chave de API do ElevenLabs for enviada a um repositório público do GitHub, o GitHub notificará o ElevenLabs e a chave será desativada automaticamente para evitar uso não autorizado.

Uma chave desativada dessa forma informa disable_reason como exposed_publicly. Para restaurar o acesso, altere a chave e atualize suas aplicações para usar a nova.

Autodesativando uma chave

Se você acredita que uma chave foi comprometida, o titular da chave pode desativá-la diretamente usando o endpoint Desativar chave de API. Chame-o com o parâmetro de consulta api_key_name=self, que é obrigatório como confirmação explícita de que você pretende desativar a chave usada para autenticar a solicitação.

Controlando quem pode desativar chaves

A configuração third_party_disable_allowed controla se uma chave pode ser desativada por seu titular, seja pelo endpoint de autodesativação ou automaticamente quando ela vazar publicamente. Por padrão, ela é ativada para planos não Enterprise e desativada para planos Enterprise.

Por chave: defina third_party_disable_allowed ao criar ou atualizar uma chave de API de conta de serviço. Omita-o para usar o padrão do workspace ou passe clear na atualização para redefinir uma chave individual ao padrão do workspace.

Em todo o workspace: os administradores do workspace podem substituir a configuração de todas as chaves de uma só vez usando o endpoint Definir política de desativação por terceiros do workspace:

• true permite que todas as chaves no workspace sejam desativadas por seu titular.
• false proíbe isso para todas as chaves.
• null remove a substituição em todo o workspace, para que o valor de cada chave e o padrão do plano voltem a ser aplicados.