---
title: "Autenticação e escopos"
description: "Autentique requisições da API do AI Glot com chaves de workspace ou tokens OAuth, escolha os escopos mínimos e rotacione credenciais sem expor segredos."
canonical: "https://ai-glot.com/docs/pt/api/authentication"
updated: "2026-08-12"
---

# Autenticação e escopos

Envie uma chave de API de workspace ou um token de acesso OAuth como uma credencial bearer:

```http title="Cabeçalho de Autorização"
Authorization: Bearer aig_live_••••••••
```

Nunca coloque uma credencial em uma query string. URLs são copiadas em logs, histórico do navegador e cabeçalhos de referenciador (referrer).

## Chaves de API de Workspace

Um administrador cria as chaves em [Ferramentas do desenvolvedor](https://app.ai-glot.com/developer). O segredo completo é exibido apenas uma vez; o AI Glot armazena apenas um hash protegido. Até 10 chaves podem estar ativas em um workspace.

![Diálogo de criação de chave de API](/docs/screenshots/platform/api-key-create.webp)

_Crie uma chave nomeada e escolha seus escopos_

Use uma chave nomeada separada para cada integração.

### Rotacionando uma chave

A lista de chaves oferece a ação **Rotacionar** (Rotate). Ela emite uma substituta com o mesmo nome, escopos e validade, revogando a original na mesma operação. A chave antiga para de funcionar imediatamente, é marcada como `replaced` (substituída) em vez de apenas revogada, e registra qual chave a sucedeu.

> **Warning**
>
> A rotação não possui período de carência nem janela de sobreposição. No momento em que você rotaciona, as requisições que ainda usam o segredo antigo falham com `api_key_revoked`. Esteja pronto para implantar o novo segredo imediatamente.

Isso é deliberado: você rotaciona porque um segredo pode ter sido comprometido, e uma chave que continue funcionando por mais uma hora continuará funcionando para quem a roubou. Para uma transição planejada e sem tempo de inatividade, crie uma segunda chave, migre a integração para ela, confirme que a chave antiga não recebe mais tráfego e, então, revogue-a.

## Tokens OAuth

O CLI e clientes MCP compatíveis podem usar OAuth 2.1. O OAuth é recomendado para pessoas, pois a conexão registra quem a aprovou e respeita o teto de acesso desse membro. Chaves de API continuam sendo a escolha certa para CI e serviços de backend.

## Escopos

Estes escopos estão disponíveis atualmente:

| Escopo             | Permite                                                                                                                                    |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `account:read`     | Identidade do workspace, plano, capacidades, limites e resumo de créditos                                                                  |
| `usage:read`       | Totais de uso e intervalos de tempo                                                                                                        |
| `batches:read`     | Listar traduções, inspecionar progresso e baixar resultados concluídos                                                                     |
| `batches:write`    | Renomear e arquivar traduções. O mesmo escopo também cobre a interrupção de uma tradução em andamento, funcionalidade ainda não disponível |
| `glossaries:read`  | Listar e recuperar glossários                                                                                                              |
| `glossaries:write` | Criar, atualizar, substituir ou excluir glossários                                                                                         |

Um escopo ausente retorna `403 insufficient_scope`.

### Escopos reservados

Mais três escopos podem ser concedidos hoje, mas nenhum endpoint os reconhece ainda. Eles aparecem na tela de consentimento do OAuth e no preset de **Acesso total** do dashboard, por isso estão documentados aqui em vez de ocultos — qualquer permissão que você seja solicitado a aprovar deve ser sempre encontrável na referência.

| Escopo           | Permitirá                                                                                             | Status                  |
| ---------------- | ----------------------------------------------------------------------------------------------------- | ----------------------- |
| `batches:create` | Iniciar uma nova tradução e aprovar uma após a etapa de revisão. Ambas consomem créditos do workspace | Indisponível no momento |
| `files:write`    | Fazer upload de arquivos para o workspace para que possam ser traduzidos                              | Indisponível no momento |
| `webhooks:write` | Criar, editar e excluir os webhooks que notificam seus sistemas quando o trabalho termina             | Indisponível no momento |

Eles existem precocemente para que uma credencial concedida agora continue funcionando no dia em que a funcionalidade for lançada, sem a necessidade de uma nova rodada de aprovação. Até lá, `GET /v1/account` reporta `capabilities.batch_creation: false` e `capabilities.webhooks: false`, e as chamadas para esses endpoints ficam indisponíveis, independentemente do escopo. Leia as flags de capacidade (`capabilities`) em vez dos escopos concedidos para decidir o que uma credencial pode realmente fazer.

## Teto do membro

Administradores do workspace podem limitar o acesso de desenvolvedores para membros. Um cliente OAuth recebe a interseção entre o que solicitou e o que o membro aprovador pode usar. Reconectar com uma solicitação mais ampla não pode ignorar um teto de apenas leitura.

> **Danger**
>
> Trate uma chave de API de workspace como uma senha. Não a envie para repositórios (commit), não a cole em JavaScript do lado do cliente, não a inclua em capturas de tela nem a envie para um modelo de IA como texto comum de prompt.