Chaves de API
Crie, configure e gerencie chaves de API no seu painel de controle.
As chaves de API autenticam suas solicitações à API. Você as gerencia completamente pelo painel de controle: defina uma categoria, restrinja o uso com cotas deslizantes, adicione uma data de expiração e monitore a atividade por chave através dos registros de solicitações.
Para saber como incluir uma chave em uma solicitação, consulte a Introdução.
Criar uma chave
Preencher os campos
Dê à chave um alias (rótulo único para sua referência), escolha uma categoria e opcionalmente configure cotas e uma data de expiração.
Copiar o segredo
Após salvar, o segredo é exibido uma única vez. Copie-o imediatamente e armazene-o em uma variável de ambiente. Ele não pode ser recuperado novamente.
Campos da chave
| Campo | Descrição |
|---|---|
| Alias | Rótulo único por conta. Aparece em registros e filtros do painel de controle. |
| Categoria | Etiqueta de organização (veja Categorias). Não afeta o comportamento da API. |
| Ativa | Ativa ou desativa a chave. Chaves inativas são rejeitadas imediatamente com 401 Inactive API Key. |
| Expira | Data opcional após a qual a chave para de funcionar. Deixe em branco para sem expiração. |
| Cotas de solicitações | Limites opcionais por chave em janelas deslizantes (veja Cotas por chave). |
Categorias
As categorias etiquetam as chaves para sua organização. Aparecem nos filtros e análises do painel de controle, mas não mudam como a API processa uma solicitação.
| Categoria | Uso típico |
|---|---|
production | Tráfego em produção, sistemas voltados ao cliente |
development | Desenvolvimento local e testes |
staging | Ambientes de pré-produção e CI |
| Personalizada | Qualquer rótulo livre, p. ex. sandbox, partner-acme |
Mantenha uma chave por ambiente para poder revogá-la ou rotacioná-la de forma independente.
Cotas por chave
Cada chave pode ter limites máximos independentes sobre o volume de solicitações, aplicados em janelas deslizantes (não limites de calendário):
| Cota | Janela |
|---|---|
| Total | Histórico: a chave é bloqueada permanentemente quando atingido |
| Diária | Últimas 24 horas (deslizante, não de meia-noite a meia-noite) |
| Semanal | Últimos 7 dias (deslizante) |
| Mensal | Últimos 30 dias (deslizante) |
Deixe um campo em branco para não aplicar limite para essa janela. Quando uma cota é atingida, a API retorna 401 Rate Limit Exceeded com o nome da cota na mensagem:
{ "error": "Rate limit exceeded: quota total" }{ "error": "Rate limit exceeded: quota daily" }{ "error": "Rate limit exceeded: quota weekly" }{ "error": "Rate limit exceeded: quota monthly" }Os contadores de cota são agregados a partir dos registros de solicitações e armazenados em cache por até 24 horas. A aplicação é precisa dentro dessa janela, não para a solicitação exata.
As cotas por chave são distintas dos limites de taxa em nível de plano (limites por segundo e por minuto que se aplicam a toda a conta). Os limites de plano retornam 429 Too Many Requests. Consulte Tratamento de erros para detalhes.
Expiração
Defina uma data de expiração em chaves usadas em scripts, pipelines de CI ou integrações com parceiros. Após a data, a API retorna:
{ "error": "Expired API Key" }Código de status HTTP 401. Crie e implante uma chave substituta antes da data de expiração para evitar qualquer tempo de inatividade.
Registros de solicitações
Cada solicitação feita com uma chave é registrada em Chaves de API → Registros no painel de controle. Cada entrada mostra:
| Campo | Descrição |
|---|---|
| Endpoint | Método HTTP e caminho |
| Status | Código de status da resposta |
| Duração | Tempo até o primeiro byte (ms) |
| IP | Endereço IP do chamador |
| Créditos | Créditos cobrados por esta solicitação |
Use os registros para auditar a atividade por chave, depurar erros inesperados ou identificar tráfego de chaves comprometidas.
Desativar vs. excluir
| Ação | Efeito |
|---|---|
| Desativar | A chave é bloqueada imediatamente. O histórico de uso e as configurações são mantidos. Pode ser reativada. |
| Excluir | Remove permanentemente a chave e sua configuração. Só é possível se a chave nunca foi usada. |
Prefira desativação à exclusão. Se uma chave tem histórico de solicitações, não pode ser excluída. O histórico é mantido para faturamento e auditoria.
Rotacionar uma chave
Criar a chave substituta
Acesse painel de controle → Chaves de API → Nova e crie uma nova chave com as mesmas configurações de categoria e cota. Dê a ela um novo alias para distingui-la.
Implantar a nova chave
Atualize a variável de ambiente em cada sistema que usa a chave antiga e reimplante.
Desativar a chave antiga
Defina a chave antiga como inativa no painel de controle. Isso bloqueia as solicitações restantes sem remover seu histórico.
Referência de erros
| Erro | Status | Causa |
|---|---|---|
Invalid API Key | 401 | Chave não encontrada ou malformada |
Inactive API Key | 401 | Chave está desativada |
Expired API Key | 401 | Chave ultrapassou sua data de expiração |
Rate limit exceeded: quota … | 401 | Cota deslizante por chave atingida |
exceeded the … rate limit on your subscription | 429 | Limite por segundo ou por minuto em nível de plano |
IP temporarily blocked | 403 | Muitas tentativas de autenticação falhas do mesmo IP |
Veja também: Melhores práticas para diretrizes de segurança e Glossário para definições de termos.