Autenticação de API e gerenciamento de chaves para ElevenAPI

A autenticação de API é a forma como um serviço verifica se uma solicitação recebida tem permissão para agir em uma conta. Por exemplo, com a ElevenAPI, as credenciais de API autorizam solicitações que consomem créditos medidos, geram voz e música em escala e, em algumas implementações, acessam áudio sensível. 

Uma chave vazada custa dinheiro e pode ser usada para gerar conteúdo na sua conta. Ela também pode conceder acesso excessivo às suas plataformas, criando potencial para vazamentos de dados e outros vetores de ataque. Já em 2020, mais de 90% dos desenvolvedores usavam APIs em pelo menos um processo diário. Agora, com o crescimento dos protocolos de contexto de modelo (MCPs) e do uso de IA, as APIs estão em todo lugar.

Este artigo explica como autenticar APIs corretamente e gerenciar chaves em todo o ciclo de vida: definição de escopo, rotação, controles organizacionais, auditoria e resposta a incidentes. Ele ajudará você a configurar corretamente a autenticação de API e o gerenciamento de chaves na sua equipe. Como referência durante a leitura, mantenha aberta a referência de autenticação e a referência de tokens de uso único.

Resumo

• A ElevenAPI autentica todas as solicitações por meio de um único segredo, o cabeçalho xi-api-key. Isso significa que qualquer pessoa que tenha uma chave pode gastar créditos e gerar áudio na conta.
• Nunca inclua uma chave de API de longa duração em um navegador, app móvel ou qualquer outro artefato que um usuário possa inspecionar. Mantenha as chaves em um servidor que você controla.
• Casos de uso no cliente devem ser autenticados com tokens de uso único e curta duração, gerados no servidor — nunca com a chave de longa duração.
• Você pode reduzir o impacto de um vazamento definindo o menor privilégio necessário para as chaves, separando chaves por ambiente e fazendo rotações programadas.
• Auditoria e detecção de anomalias ajudam a evitar vazamentos de chaves e surpresas.

O que é autenticação de API?

A autenticação de API é como um serviço confirma que uma solicitação recebida pode agir em uma conta específica antes de começar a processá-la. Quem faz a solicitação apresenta a credencial, o serviço a verifica e, após a verificação, fornece uma resposta. 

Em resumo, ela responde: esta solicitação está autorizada a agir em nome desta conta? É importante observar que esse processo é diferente da autorização de API, que define o que uma solicitação autenticada pode fazer no seu sistema.

O que é gerenciamento de chaves?

Gerenciamento de chaves é o conjunto mais amplo de práticas usado para controlar uma chave de API durante todo o ciclo de vida. Ele define como você cria, armazena, usa, rotaciona e revoga o acesso às chaves. Esses sistemas existem para garantir a segurança de ponta a ponta de uma chave de API. 

Com sistemas rigorosos de gerenciamento de chaves, você consegue evitar chaves expostas e reduzir o risco de que se tornem publicamente acessíveis. 

Por que a segurança de chaves de API importa: o modelo de ameaças

Agora que autenticação e gerenciamento de chaves foram definidos, vale entender com precisão o que dá errado quando uma chave é mal administrada. Examinar primeiro o modelo de ameaças dá um propósito claro a cada prática explorada a seguir: todas reduzem a chance de uma chave vazar ou o dano causado quando isso acontece.

A ElevenAPI autentica por meio de um único mecanismo baseado em segredo: o cabeçalho xi-api-key. Qualquer pessoa que tenha a chave está autorizada, e não há um segundo fator na própria solicitação.

Com sua chave, alguém pode gastar seus créditos. Text to Speech, Speech to Text, música e efeitos sonoros são cobrados por uso, e um invasor com uma chave válida pode gerar conteúdo continuamente até esgotar sua cota ou saldo.

Também é possível gerar conteúdo em escala, e nosso modelo de limitação de taxa torna a situação mais significativa do que parece. O limite se baseia em concorrência, não em uma simples cota de solicitações por minuto. Uma chave em um plano com limite de concorrência de cinco para determinada família de modelos pode sustentar várias gerações simultâneas, e um invasor que entenda esses limites paralelizará o abuso.

Também é possível produzir conteúdo na sua conta. Todo áudio gerado com sua chave é atribuído ao seu workspace e, dependendo das vozes e entradas envolvidas, isso pode gerar preocupações reputacionais e, ocasionalmente, legais.

As formas de chaves vazarem são comuns e correspondem aos mesmos modos de falha que expõem qualquer outro tipo de credencial:

• Chaves de API no código do cliente: Uma chave incluída em um bundle de navegador, binário móvel ou app de página única é, na prática, pública. Minificação não é ofuscação.
• Chaves de API em repositórios: Chaves codificadas diretamente e enviadas ao Git, incluindo repositórios privados que depois se tornam públicos ou são amplamente clonados, além de arquivos como .env que nunca deveriam ser rastreados.
• Chaves de API em logs e rastreamentos: Registradores de solicitações, rastreadores de erros e pipelines de observabilidade capturam cabeçalhos HTTP rotineiramente. Uma chave em xi-api-key acaba no seu armazenamento de logs, no fornecedor de APM e com qualquer pessoa que tenha acesso de leitura a um deles.
• Chaves de API em CI e capturas de tela: Logs de build, tickets de suporte e terminais compartilhados.

Cada seção abaixo ajuda a reduzir a probabilidade ou o impacto de uma dessas situações.

A regra fundamental: mantenha as chaves de API no servidor

Todo o restante deste artigo oferece orientações para reduzir riscos na autenticação e no gerenciamento de chaves de API. Esta regra é a base de tudo e deve ser implementada acima de qualquer outra medida.

Como o mecanismo é tão simples, a regra fundamental é que uma chave de API de longa duração deve ficar apenas em um servidor que você controla. Ela nunca deve ser incluída em um navegador, app móvel, cliente desktop ou qualquer artefato que um usuário possa baixar e inspecionar. Se a chave estiver no código do cliente, trate-a como já comprometida.

O SDK lê ELEVENLABS_API_KEY automaticamente. Portanto, o código mais limpo não passa nada e inicializa o cliente apenas uma 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",
});

Em produção, ela deve ser preenchida a partir de um gerenciador de segredos (AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault ou o equivalente da sua plataforma) na inicialização do processo, e não incorporada a uma imagem ou a um .env enviado ao repositório.

Tokens de uso único para apps no cliente

A regra fundamental é absoluta, mas muitos casos de uso legítimos exigem que o próprio cliente acesse a ElevenAPI: um navegador reproduzindo Text to Speech por streaming, um app móvel capturando áudio para transcrição ou um agente em tempo real executado na aba do usuário. A chave de longa duração não pode ir para esses locais. A solução é fornecer ao cliente uma credencial de baixo risco em caso de vazamento: um token de uso único e curta duração.

Seu servidor mantém a chave de longa duração, autentica e autoriza o usuário com a sua própria lógica de sessão e, então, gera um token de curta duração e entrega apenas ele ao cliente. O token expira rapidamente e tem escopo para a operação para a qual foi emitido, então um token vazado vale pouco e logo não vale nada. Consulte a referência de tokens de uso único para ver os endpoints compatíveis e o formato exato da solicitação.

Esta é a lógica essencial de um endpoint intermediário. Ele autoriza o usuário com sua própria lógica de sessão e gera um token no endpoint de tokens documentado. A solicitação sai do servidor com a xi-api-key de longa duração, e apenas o token resultante de curta duração retorna ao 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() });
});

O navegador então usa esse token para se conectar, e a chave de longa duração nunca entra na página.

Definir chaves com o menor privilégio necessário

Menor privilégio é o princípio de que cada chave deve ter somente as permissões necessárias para sua função, e nada além disso. A ElevenAPI permite implementar várias restrições baseadas em permissões que limitam o que uma chave pode e não pode fazer.

Uma única chave com todos os poderes é o pior cenário em termos de impacto de um vazamento, além de ser a opção padrão mais fácil. Uma abordagem melhor é presumir que qualquer chave acabará vazando e garantir que, quando isso acontecer, ela só possa fazer o necessário para sua função.

Comece restringindo o escopo, o que limita quais endpoints da API uma chave pode chamar. Uma chave usada apenas para transcrição não precisa de acesso ao Text to Speech; uma chave para um recurso de música não precisa acessar o gerenciamento de vozes.

Em seguida, há a cota de créditos. Atribuir um limite personalizado de créditos por chave limita o prejuízo financeiro de um vazamento e também contém loops descontrolados no seu próprio código.

A lista de permissões de IP vai além. Você pode restringir uma chave a endereços IP ou intervalos CIDR específicos, e solicitações de IPs fora da lista são rejeitadas com um 403. Este é um recurso Enterprise atualmente em prévia, disponível por meio do seu gerente de conta.

Por fim, não compartilhe uma chave entre desenvolvimento, homologação e produção. Emita uma chave distinta por ambiente, cada uma com seu próprio escopo e cota. As chaves por ambiente isolam créditos de produção de um vazamento no notebook de um desenvolvedor, permitem rotacionar um ambiente sem afetar os outros e tornam os logs de uso compreensíveis, pois o tráfego já está segmentado por origem.

Rotação de chaves de API

Rotação de chaves é a prática de substituir uma chave por outra nova regularmente. Também é uma medida que você pode tomar sempre que suspeitar de uma violação ou exposição.

Quando feita em uma programação, a rotação também reduz a janela em que um vazamento não percebido pode ser explorado. Ela só é simples se seu código tiver sido criado para isso; portanto, planeje a rotação antes de precisar dela.

A técnica principal é sobrepor chaves, permitindo uma transição sem tempo de inatividade:

1. Gere uma nova chave de API: Crie uma nova chave ao lado da existente, com o mesmo escopo, cota e restrições de IP. Ambas estarão válidas.
2. Atualize a chave: Distribua a nova chave atualizando o segredo no seu gerenciador de segredos e permitindo que as instâncias o obtenham novamente (por reinicialização, nova leitura ou atualização do gerenciador, dependendo da configuração).
3. Confirme o tráfego: Verifique se o tráfego está fluindo pela nova chave. Monitore o uso para confirmar que a chave antiga deixou de ser usada.
4. Remova o acesso da chave: Revogue a chave antiga quando ela não apresentar tráfego durante uma janela segura.

Como ambas as chaves são válidas durante a sobreposição, nunca há um momento em que as solicitações falham por falta de credencial. A janela de sobreposição também traz outro benefício: uma instância mal configurada se revela ao continuar usando a chave antiga, para que você possa encontrá-la antes de revogar essa chave.

Para que a sobreposição transcorra sem problemas, estruture o código de modo que a rotação seja uma mudança de configuração, nunca de código. Leia a chave em um único lugar, onde ela possa ser atualizada, e deixe uma única chave de configuração decidir qual segredo está ativo.

// 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 uma sobreposição, mantenha PRIMARY e SECONDARY preenchidas e alterne ELEVENLABS_KEY_ACTIVE. O código da aplicação nunca muda.

Quanto à frequência, uma rotação de rotina a cada 90 dias é um padrão razoável para chaves de backend; faça isso com mais frequência para chaves de alto valor ou muito acessadas e imediatamente em caso de exposição. Isso pode ser automatizado com uma tarefa agendada que cria, distribui, verifica e revoga chaves, transformando a rotação de um evento em um processo de segundo plano.

Controles de acesso e permissões do workspace

Enquanto o escopo e a rotação protegem chaves individuais, os controles do workspace definem quem pode criá-las. Eles permitem definir e seguir uma política organizacional que influenciará todas as suas práticas futuras de gerenciamento de chaves.

Comece separando credenciais humanas das de máquinas. Pessoas acessam o painel com suas próprias contas e permissões; serviços são autenticados com chaves ou, melhor ainda, contas de serviço. Não permita que um serviço opere com uma chave criada a partir do acesso pessoal de alguém e não deixe pessoas compartilharem uma única chave de máquina. O motivo é o desligamento: quando uma pessoa sai ou um serviço é aposentado, você quer revogar exatamente a credencial certa, sem danos colaterais.

As contas de serviço têm o mesmo objetivo. Elas dão às cargas de trabalho de máquinas uma identidade não vinculada a uma pessoa, com seu próprio escopo, mantendo sua trilha de auditoria precisa.

Depois, mapeie o acesso por funções, em vez de atribuí-lo individualmente. Os workspaces oferecem permissões de grupos e membros exatamente para isso. Conceda o menor privilégio que permita a cada grupo trabalhar, revise as associações periodicamente e busque uma estrutura em que nenhuma credencial, humana ou de máquina, possa fazer mais do que sua função exige.

Auditoria e detecção

Nas etapas anteriores, explicamos como reduzir o dano de um vazamento. Nesta etapa, explicaremos como detectar se um vazamento aconteceu. Uma boa detecção depende de três hábitos. 

O primeiro é registrar qual chave — pelo identificador, nunca pelo valor secreto — atendeu qual tipo de solicitação, de onde e em que volume. Remova o cabeçalho xi-api-key de todas as camadas de registro e rastreamento. Uma regra de ocultação no middleware HTTP e na configuração de APM elimina a forma mais comum de chaves acabarem em armazenamentos de logs.

O segundo é monitorar o consumo de créditos em busca de anomalias. Acompanhe o gasto de créditos por chave ao longo do tempo e alerte sobre desvios da linha de base: um pico repentino, gerações em horários incomuns ou uma chave que deveria estar inativa e passa a ser usada.

O terceiro é monitorar os cabeçalhos de concorrência. Retornamos as solicitações concorrentes atuais e máximas em cada resposta, nos cabeçalhos current-concurrent-requests e maximum-concurrent-requests. Eles mostram sua capacidade disponível, e uma permanência no máximo que você não iniciou é um forte sinal de abuso. Usar o endpoint HTTP bruto expõe diretamente os cabeçalhos da resposta:

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.

Isso deve disparar alertas. Um painel que ninguém acompanha não oferece detecção. Direcione sinais de picos de crédito e saturação de concorrência para o mesmo fluxo de alertas usado para indisponibilidades, com um responsável claro.

Resposta a incidentes

Mesmo com os melhores sistemas possíveis de segurança e monitoramento, você ainda precisa presumir que uma chave acabará vazando. Planejar essa possibilidade com uma lista de medidas para limitar os danos oferece um roteiro de resposta que economiza tempo e reduz o impacto.

Este é um fluxo predefinido de resposta a incidentes para exposição de chaves de API:

1. Revogue a chave vazada imediatamente: Não espere entender toda a extensão do problema. Uma chave revogada não pode gerar conteúdo, e a revogação é reversível no sentido de que você sempre pode emitir uma substituta. Esta é a ação individual mais valiosa.
2. Faça a rotação para uma nova chave: Se a chave vazada atendia tráfego de produção, use o procedimento de sobreposição ao contrário: crie uma nova chave, redirecione o tráfego e confirme que a chave vazada foi desativada. Como seu código lê a chave da configuração, isso é uma alteração de configuração, não de código.
3. Avalie o impacto pelos logs de uso: Com o vazamento contido, quantifique-o. Por quanto tempo a chave esteve válida e exposta? Quais créditos foram consumidos nesse período e o padrão corresponde a tráfego legítimo ou abuso? Quais endpoints ela acessou?
4. Rotacione segredos dependentes: Uma chave raramente vaza sozinha. Se ela foi exposta em um repositório, armazenamento de logs ou pipeline de CI, presuma que segredos próximos no mesmo local também foram expostos e rotacione-os.
5. Feche o caminho do vazamento: Descubra como a chave vazou e corrija a causa, ou isso acontecerá de novo: adicione o arquivo ao .gitignore e elimine-o do histórico, oculte cabeçalhos no registrador, remova o segredo do artefato de build e restrinja o acesso ao sistema de CI.
6. Escreva o post-mortem: Documente a linha do tempo, o impacto, a causa raiz e os controles concretos adicionados (restrição de escopo, lista de permissões de IP, scanner de segredos no CI e rotação mais frequente).

Ao seguir essas etapas, você terá um processo confiável para cenários de desastre envolvendo exposição de APIs. 

Postura de conformidade: SOC 2, HIPAA e retenção de dados

A autenticação é um dos elementos de uma avaliação de conformidade mais ampla, e é importante ter cautela sobre o que pode e não pode ser afirmado aqui. Considere os pontos a seguir como informações factuais iniciais, não como uma determinação para seu caso de uso.

A ElevenLabs está em conformidade com SOC 2. Para planos e casos de uso elegíveis, estão disponíveis conformidade com HIPAA e modos de retenção zero. Retenção zero significa que o conteúdo da solicitação não é armazenado após o processamento, o que é importante quando suas entradas ou o áudio gerado são sensíveis.

A aplicação de determinado modo depende do seu plano, configuração e das especificidades do que você processa. Confirme a elegibilidade e os termos exatos da sua conta antes de depender de qualquer um deles e combine-os com os controles de acesso descritos acima. Certificações de conformidade regem como a plataforma lida com seus dados; o gerenciamento de chaves rege quem pode agir em seu nome, e essa parte é sua responsabilidade.

Como é uma boa segurança de chaves de API

Chaves somente no servidor eliminam a maior superfície de vazamento. Tokens de uso único estendem essa garantia aos clientes que realmente precisam acessar nossa API. A definição de escopo e a separação por ambiente limitam o dano de qualquer vazamento. A rotação incorporada à configuração torna a recuperação rotineira em vez de arriscada. Os controles de workspace mantêm distintas as identidades humanas e de máquinas. A auditoria transforma abuso em alerta, não em surpresa na sua fatura. Um manual de procedimentos transforma um incidente em um processo.

É a mesma higiene de credenciais que protege qualquer segredo de alto valor, aplicada a uma chave cujo valor particular é gastar dinheiro e gerar áudio em escala.

Quando estiver pronto para implementar isso com os formatos reais de solicitação, a referência de autenticação e a referência de tokens de uso único oferecem a lista atual de endpoints compatíveis. Para entender o modelo de concorrência que seu monitoramento deve acompanhar, a referência de modelos e o guia rápido da API são as próximas leituras ideais.

Proteja sua integração com a ElevenAPI

Uma autenticação de API robusta é um controle fundamental sobre o qual várias outras práticas de segurança se apoiam. Medidas como usar chaves somente no servidor, implementar tokens de uso único para clientes, definir o menor privilégio necessário e incorporar a rotação ao gerenciamento de chaves ajudam a prevenir riscos em escala.

Para mais informações sobre endpoints compatíveis e o formato exato de cabeçalho a usar, consulte a documentação da ElevenAPI. Se estiver pronto para começar, solicite uma chave de API da ElevenLabs e comece a desenvolver hoje. 

Perguntas frequentes sobre autenticação de API e gerenciamento de chaves