Chaves de API

As chaves de API autenticam o acesso de máquina (scripts, cron jobs e o servidor MCP embutido) à API REST do Chinaski. O acesso vive em Settings → API Keys (/admin/api-keys), apenas admin. Esta página cobre criá-las, dar escopo a elas e revogá-las; o modelo de requisição (escopos, rate limits) fica na própria página de Automação.

Criando uma chave

Clique em criar; dê à chave um nome (obrigatório; os nomes são os identificadores eternos de auditoria) e uma permissão:
- read: pode buscar conteúdo, mas nunca modificar.
- write: pode criar e atualizar; exigida para toda chamada de mutação.
Opcionalmente defina uma data de expiração (uma data simples; deixá-la vazia significa que a chave nunca expira).
A chave em si é uma longa string aleatória gerada por uma fonte segura de aleatoriedade, mostrada exatamente uma vez em um campo de cópia logo após a criação, com uma nota explícita de que não será mostrada de novo. Apenas um hash dela é armazenado (e para chaves recém-criadas, uma camada de verificação bcrypt por cima), de modo que um vazamento de banco de dados não possa revelar chaves vivas.
As criações são auditadas (a ação nomeia a chave e seu escopo).

Escopo na prática

Os cards agrupam leitura/escrita por design (flux-group): o escopo de leitura não pode criar ou editar nada.
O escopo de escrita é exigido para todo endpoint manipulador de conteúdo, tanto para caminhos "seguros" quanto administrativos, de modo que uma chave cunhada como um reportador somente leitura não possa espiar pelo portão batendo numa rota menos conhecida.
Um portão de asserção amplo, à frente das rotas autenticadas por sessão, agora checa o escopo por método, para que chamadas de escrita com chaves de leitura recebam um 403 limpo em vez de um sangramento silencioso de permissões.

Limitação de taxa

O rate limiting é por chave, por janela móvel de 60 segundos, com padrão de 100 requisições por minuto (configurável em Settings → Security: "API key rate limit"). Cruzar o limite retorna uma resposta 429 com um header Retry-After dizendo ao script quanto esperar. Cada requisição incrementa o contador exatamente uma vez, independente de quantas camadas internas de autenticação atravessar.

Feedback de uso da chave: cada chave registra a última vez que autenticou; o uso recente é visível na tela de chaves, e cada requisição é auditada (método e caminho), que é a forma mais rápida de encontrar chaves abandonadas.

O kill switch

A chave mestre "API access" na mesma tela desabilita todas as requisições de API, em uma única chave. Com o acesso desligado, a API responde a toda requisição com um 503, ignorando as chaves, o que é útil durante incidentes sem caçar sua lista de chaves. A ação da chave em si é auditada com o estado resultante.

Revogação

Apagar uma chave é instantâneo e auditado: a chave para de funcionar imediatamente depois. O hábito de limpeza mais seguro: a trilha de auditoria encontra as datas de último uso por chave; uma chave com um timestamp de último uso obsoleto e uma origem de execução de teste compõe uma política de aposentadoria organizada.