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

A autenticação de API é o processo pelo qual um serviço verifica se uma solicitação recebida está autorizada a agir em uma conta. Por exemplo, com a ElevenAPI, as credenciais de API autorizam solicitações que consomem créditos, geram áudio e música em escala e, em alguns casos, acessam conteúdos sensíveis.

Uma chave vazada pode gerar custos e ser usada para criar conteúdo na sua conta. Ela também pode dar acesso excessivo às suas plataformas, aumentando o risco de vazamento de dados e outros tipos 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 modelos (MCPs) e do uso de IA, as APIs estão em todo lugar.

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

Resumo rápido

• O ElevenAPI autentica cada solicitação por meio de um único segredo, o header xi-api-key. Ou seja, qualquer pessoa com a chave pode gastar créditos e gerar áudio na conta.
• Nunca envie uma chave de API de longa duração em um navegador, app móvel ou qualquer outro artefato que o usuário possa inspecionar. Mantenha as chaves apenas em servidores sob seu controle.
• Em casos de uso no lado do cliente, a autenticação deve ser feita 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 limitando o escopo das chaves, separando por ambiente e fazendo rotação periódica.
• Auditoria e detecção de anomalias ajudam a evitar vazamentos e surpresas.

O que é autenticação de API?

A autenticação de API é o processo pelo qual um serviço confirma se uma solicitação recebida pode agir em uma conta específica antes de executar qualquer ação. O solicitante apresenta a credencial, o serviço verifica e, se estiver tudo certo, responde.

Resumindo: responde à pergunta 'Esta solicitação está autorizada a agir por esta conta?'. Vale lembrar que isso é diferente de autorização, que define o que uma solicitação autenticada pode ou não fazer no seu sistema.

O que é gerenciamento de chaves?

Gerenciamento de chaves é o conjunto de práticas para controlar uma chave de API durante todo o seu ciclo de vida. Isso inclui como criar, armazenar, usar, rotacionar e revogar o acesso às chaves. Esses sistemas garantem a segurança da chave de ponta a ponta.

Com um gerenciamento rigoroso, você evita vazamentos e reduz o risco de as chaves se tornarem públicas.

Por que a segurança das chaves de API é importante: modelo de ameaça

Agora que já definimos autenticação e gerenciamento de chaves, vale detalhar o que pode dar errado quando uma chave é mal utilizada. Entender o modelo de ameaça desde o início garante que cada prática adotada tenha um objetivo claro: reduzir a chance de vazamento ou o impacto caso ele aconteça.

O ElevenAPI autentica por meio de um único mecanismo: o header xi-api-key. Quem tem a chave está autorizado, sem necessidade de segundo fator na solicitação.

Com sua chave, alguém pode gastar seus créditos. Transformar Texto em Áudio, Speech to Text, música e efeitos sonoros são todos tarifados, e um invasor com uma chave válida pode gerar conteúdo até esgotar sua cota ou saldo.

Eles podem gerar em escala, e nosso modelo de limitação de taxa torna isso ainda mais relevante. O limite é baseado em concorrência, não apenas em solicitações por minuto. Uma chave em um plano com limite de cinco concorrências para uma família de modelos pode sustentar várias gerações simultâneas, e um invasor que entende esses limites pode abusar disso em paralelo.

Eles podem produzir conteúdo na sua conta. Todo áudio gerado com sua chave é atribuído ao seu workspace e, dependendo das vozes e entradas usadas, isso pode ser um problema de reputação ou até mesmo legal.

As formas de vazamento de chaves são comuns e seguem os mesmos padrões de falha de outros tipos de credenciais:

• Chaves de API em código do lado do cliente: Uma chave enviada 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 fixas no código enviadas para o Git, inclusive em repositórios privados que podem se tornar públicos ou ser amplamente clonados, e arquivos como .env que nunca deveriam ser versionados.
• Chaves de API em logs e rastreamentos: Logs de requisição, rastreadores de erro e pipelines de observabilidade frequentemente capturam headers HTTP. Uma chave no xi-api-key pode acabar no seu log, no fornecedor de APM e para qualquer pessoa com acesso de leitura.
• Chaves de API em CI e capturas de tela: Logs de build, chamados de suporte e terminais compartilhados.

Cada seção abaixo mostra como reduzir a probabilidade ou o impacto de cada um desses cenários.

A regra de ouro: mantenha as chaves de API no servidor

Todo o restante deste artigo traz dicas para reduzir riscos na autenticação e no gerenciamento de chaves de API. Mas esta é a base de tudo e deve ser seguida acima de qualquer outra.

Como o mecanismo é simples, a regra de ouro é: uma chave de API de longa duração deve ficar apenas em um servidor sob seu controle. Nunca envie a chave em navegador, app móvel, cliente desktop ou qualquer artefato que o usuário possa baixar e inspecionar. Se a chave está no código do lado do cliente, considere-a comprometida.

O SDK lê automaticamente ELEVENLABS_API_KEY, então o código mais limpo não precisa passar nada e inicializa o cliente uma única 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, a chave deve ser carregada de um gerenciador de segredos (AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault ou equivalente da sua plataforma) ao iniciar o processo, nunca embutida em uma imagem ou em um .env versionado.

Tokens de uso único para apps do lado do cliente

A regra de ouro é absoluta, mas muitos casos legítimos exigem que o cliente acesse o ElevenAPI: um navegador tocando áudio de Transformar Texto em Áudio, um app móvel capturando áudio para transcrição ou um agente em tempo real rodando na aba do usuário. A chave de longa duração não pode ir para lá. A solução é dar 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 sua própria lógica de sessão e, então, gera um token de curta duração e entrega apenas esse token ao cliente. O token expira rápido e tem escopo restrito à operação para a qual foi emitido, então um token vazado vale pouco e logo não vale nada. Veja a referência de tokens de uso único para os endpoints suportados e o formato exato da solicitação.

Aqui está a lógica essencial de um endpoint intermediário. Ele autoriza o usuário com sua lógica de sessão e, então, gera um token no endpoint de tokens documentado. A solicitação sai com o xi-api-key de longa duração do servidor, e só o token de curta duração retorna para o 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 usa esse token para se conectar, e a chave de longa duração nunca entra na página.

Limitando o escopo das chaves (least privilege)

O princípio do menor privilégio diz que cada chave deve ter apenas as permissões necessárias para sua função, e nada além disso. O ElevenAPI permite implementar várias restrições baseadas em permissões para limitar o que cada chave pode ou não fazer.

Uma única chave com todos os poderes é o pior cenário em caso de vazamento — e também o padrão mais fácil. O ideal é assumir que qualquer chave pode vazar um dia e garantir que, se isso acontecer, ela só possa fazer o necessário para sua função.

Comece restringindo o escopo, limitando quais endpoints de API a chave pode acessar. Uma chave usada só para transcrição não precisa de acesso a Transformar Texto em Áudio; uma chave para música não precisa acessar gerenciamento de voz.

Depois, defina um limite de créditos por chave. Isso limita o prejuízo financeiro em caso de vazamento e também evita loops descontrolados no seu próprio código.

A restrição por IP vai além. Você pode limitar uma chave a IPs ou faixas CIDR específicas, e solicitações de IPs não autorizados são rejeitadas com erro 403. Esse recurso está em prévia para clientes Enterprise, disponível pelo gerente de conta.

Por fim, nunca compartilhe uma chave entre desenvolvimento, homologação e produção. Gere uma chave diferente para cada ambiente, cada uma com seu próprio escopo e limite. Assim, um vazamento no laptop do desenvolvedor não afeta os créditos de produção, você pode rotacionar um ambiente sem impactar os outros e os logs ficam mais fáceis de interpretar, já que 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 ação recomendada sempre que houver suspeita de vazamento ou exposição.

Com uma rotina, a rotação reduz o tempo em que um vazamento não detectado pode ser explorado. Mas só é fácil se seu código estiver preparado para isso, então pense na rotação antes de precisar dela.

A técnica principal é usar chaves sobrepostas, permitindo a troca sem downtime:

1. Gere uma nova chave de API: Provisione uma nova chave junto com a existente, com o mesmo escopo, limite e restrições de IP. Ambas ficam válidas.
2. Atualize a chave: Implemente a nova chave atualizando o segredo no gerenciador de segredos e deixando as instâncias capturarem a mudança (reinício, recarregamento ou atualização do segredo, dependendo do seu setup).
3. Confirme o tráfego: Verifique se o tráfego está passando pela nova chave. Acompanhe o uso para garantir que a chave antiga ficou inativa.
4. Remova o acesso da chave: Revogue a chave antiga assim que ela não apresentar mais tráfego por um período seguro.

Como ambas as chaves ficam válidas durante a sobreposição, não há momento em que as solicitações falham por falta de credencial. A sobreposição tem outro benefício: uma instância mal configurada se revela ao continuar usando a chave antiga, permitindo identificá-la antes de revogar o acesso.

Para que a sobreposição seja tranquila, estruture seu código para que a rotação seja uma mudança de configuração, nunca de código. Leia a chave de um único lugar, de forma que possa ser atualizada, e use um único parâmetro para definir 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 a sobreposição, mantenha PRIMARY e SECONDARY preenchidas e alterne ELEVENLABS_KEY_ACTIVE. O código da aplicação não muda.

Como rotina, uma rotação a cada 90 dias é um bom padrão para chaves de backend, com frequência maior para chaves de alto valor ou muito acessadas, e imediata em caso de exposição. Isso pode ser automatizado com um job agendado que gera, troca, verifica e revoga, tornando a rotação um processo de fundo.

Controles de acesso e permissões do workspace

Enquanto escopo e rotação protegem chaves individuais, os controles do workspace definem quem pode criá-las. É o espaço para definir e seguir políticas organizacionais, que vão influenciar todas as práticas de gerenciamento de chaves no futuro.

Comece separando credenciais de pessoas e de máquinas. Pessoas acessam o painel com suas próprias contas e permissões; serviços autenticam com chaves ou, de preferência, contas de serviço. Não deixe um serviço rodar com chave gerada por acesso pessoal e não permita que pessoas compartilhem uma chave de máquina. O motivo é o offboarding: quando alguém sai ou um serviço é desativado, você quer revogar só a credencial certa, sem afetar o restante.

Contas de serviço têm o mesmo objetivo. Elas dão identidade própria para cargas de trabalho de máquina, com escopo próprio, mantendo a trilha de auditoria confiável.

Depois, mapeie o acesso por função, não por pessoa. O workspace permite permissões por grupo e membro para isso. Dê o menor privilégio necessário para cada grupo, revise a composição periodicamente e busque um arranjo 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, mostramos como reduzir o impacto de um vazamento. Agora, vamos ver 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 do segredo) atendeu qual tipo de solicitação, de onde e em qual volume. Remova o header xi-api-key de todos os logs e rastreamentos. Uma regra de remoção no seu middleware HTTP e na configuração do APM elimina a forma mais comum de chaves irem parar em 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 configure alertas para desvios do padrão: picos repentinos, geração em horários incomuns ou uma chave que deveria estar inativa ficando ativa de repente.

O terceiro é observar os headers de concorrência. Retornamos o número atual e máximo de solicitações simultâneas em cada resposta, nos headers current-concurrent-requests e maximum-concurrent-requests. Eles mostram quanto espaço você tem, e um uso constante no máximo sem sua ação é sinal forte de abuso. Usar o endpoint HTTP direto expõe esses headers na 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.

Esses casos devem gerar alertas. Um painel que ninguém monitora não serve para detecção. Integre alertas de pico de crédito e saturação de concorrência no mesmo fluxo de alertas de indisponibilidade, com um responsável claro.

Resposta a incidentes

Mesmo com os melhores sistemas de segurança e monitoramento, é preciso assumir que uma chave pode vazar um dia. Ter um plano de ação para limitar danos agiliza a resposta e reduz o impacto.

Veja um roteiro pré-definido para resposta a incidentes de vazamento de chave de API:

1. Revogue a chave vazada imediatamente: Não espere entender todo o cenário. Uma chave revogada não gera mais nada, e a revogação é reversível — você pode emitir uma nova. Essa é a ação mais importante.
2. Gere uma nova chave: Se a chave vazada atendia produção, use o procedimento de sobreposição ao contrário: crie uma nova, direcione o tráfego, depois confirme que a vazada está inativa. Como seu código lê a chave da configuração, basta trocar o parâmetro, sem mudar o código.
3. Avalie o impacto pelos logs de uso: Com o vazamento contido, quantifique. Por quanto tempo a chave ficou exposta? Quantos créditos foram consumidos nesse período? O padrão de uso era legítimo ou abuso? Quais endpoints foram acessados?
4. Gire segredos dependentes: Uma chave raramente vaza sozinha. Se ela foi exposta em repositório, log ou pipeline de CI, assuma que outros segredos próximos também vazaram e gire todos.
5. Feche o caminho do vazamento: Descubra como a chave vazou e corrija, ou vai acontecer de novo: adicione o arquivo ao .gitignore e limpe o histórico, adicione remoção de header ao logger, mova o segredo para fora do artefato de build e restrinja o acesso ao CI.
6. Registre o pós-morte: Documente a linha do tempo, o impacto, a causa raiz e os controles implementados (restrição de escopo, whitelist de IP, scanner de segredos no CI, rotação mais frequente).

Seguindo esses passos, você terá um processo pronto para lidar com cenários de exposição de API.

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

A autenticação é apenas um dos pontos avaliados em conformidade, e é importante ser preciso sobre o que pode ou não ser declarado aqui. Considere as informações abaixo como ponto de partida, não como definição para seu caso.

A ElevenLabs é compatível com SOC 2. Para planos e usos elegíveis, há 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 seus dados ou áudios gerados são sensíveis.

Se um modo se aplica ou não depende do seu plano, configuração e do que está sendo processado. Confirme a elegibilidade e os termos exatos para sua conta antes de confiar em qualquer um deles e combine com os controles de acesso descritos acima. Certificações de conformidade definem como a plataforma trata seus dados; o gerenciamento de chaves define quem pode agir em seu nome — e essa parte é sua responsabilidade.

Como deve ser a segurança de chaves de API

Chaves apenas no servidor eliminam o maior risco de vazamento. Tokens de uso único estendem essa proteção aos clientes que realmente precisam acessar nossa API. Escopo restrito e separação por ambiente limitam o dano de um vazamento. Rotação configurável torna a recuperação rotineira, não arriscada. Controles do workspace separam identidades humanas e de máquina. Auditoria transforma abuso em alerta, não em surpresa na fatura. Um procedimento escrito transforma incidentes em processos claros.

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

Quando quiser implementar isso nos formatos reais de requisição, consulte a referência de autenticação e a referência de tokens de uso único para ver a lista atual de endpoints suportados. Para entender o modelo de concorrência que seu monitoramento deve acompanhar, consulte a referência de modelos e o guia rápido da API.

Proteja sua integração com o ElevenAPI

Uma autenticação forte de API é um controle fundamental sobre o qual várias outras práticas de segurança se apoiam. Medidas como usar chaves apenas no servidor, tokens de uso único para clientes, escopo restrito e rotação integrada ao gerenciamento de chaves ajudam a prevenir riscos em escala.

Para mais informações sobre endpoints suportados e o formato exato do header, consulte a documentação do ElevenAPI. Se quiser começar agora, solicite uma chave de API da ElevenLabs e comece a criar hoje mesmo.

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