> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.

# 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](#expiring-user-api-keys) 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](/docs/pt/overview/administration/workspaces/members#full-seats).
* As **chaves de API de conta de serviço** pertencem a uma [conta de serviço](/docs/pt/overview/administration/workspaces/service-accounts), 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](/docs/pt/api-reference/authentication).

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](#ip-allowlisting).

## 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](https://elevenlabs.io/app/settings/api-keys). 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`](/docs/pt/eleven-api/resources/errors). Você pode estender ou remover a expiração editando a chave antes que ela expire; caso contrário, [altere](#rotating-api-keys) para uma nova chave.

> **Note**
>
> A expiração se aplica apenas a chaves de API de usuário. As chaves de API de conta de serviço são destinadas a cargas de trabalho de backend
> e produção de longa duração, por isso não expiram.

## Alternando chaves de API

> **Info**
>
> Ao criar uma nova chave de API para substituir outra que está sendo alternada, copie as permissões da
> chave antiga para a nova, para que nenhum acesso seja perdido. Para chaves de conta de serviço, crie a
> nova chave para a mesma conta de serviço.

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](https://elevenlabs.io/app/settings/api-keys), 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](/docs/pt/api-reference/service-accounts/api-keys/create) para a mesma conta de serviço e depois [exclua a antiga](/docs/pt/api-reference/service-accounts/api-keys/delete).

## 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`](/docs/pt/eleven-api/resources/errors).

### 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).

> **Note**
>
> Intervalos de IP privados (por exemplo, `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`) não são aceitos. Apenas
> endereços IP públicos podem ser incluídos na lista de permitidos.

## Detectando chaves vazadas

O ElevenLabs participa do [programa de parceiros de escaneamento de segredos do GitHub](https://docs.github.com/en/code-security/secret-scanning/secret-scanning-partner-program). 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](#rotating-api-keys) e atualize suas aplicações para usar a nova.

> **Note**
>
> A desativação automática de chaves vazadas só se aplica quando a desativação por terceiros é permitida para a chave.
> Consulte [Controlando quem pode desativar chaves](#controlling-who-can-disable-keys).

## 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](/docs/pt/api-reference/api-keys/disable). 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.

> **Note**
>
> Um e-mail de notificação é enviado ao proprietário do workspace e ao proprietário da chave quando uma chave é desativada por
> terceiros, seja automaticamente pelo escaneamento de segredos do GitHub ou pelo endpoint de autodesativação.
> Desativar uma chave você mesmo na interface web não envia uma notificação.

**Por chave:** defina `third_party_disable_allowed` ao [criar](/docs/pt/api-reference/service-accounts/api-keys/create) ou [atualizar](/docs/pt/api-reference/service-accounts/api-keys/update) 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](/docs/pt/api-reference/api-keys/set-third-party-disabling-policy):

* `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.