# Segurança na atualização de versão da API para agentes de IA

Uma atualização de API pode ampliar a autoridade de um agente sem mudar uma única linha de suas instruções. As mudanças perigosas costumam parecer inofensivas nas notas de versão: um padrão muda, surge um endpoint, um token legado ganha um caminho de compatibilidade ou uma resposta passa a incluir registros que a versão antiga omitia.

Integrações operadas por pessoas às vezes sobrevivem a essa ambiguidade porque alguém percebe uma tela desconhecida ou para antes de fazer uma solicitação estranha. Um agente autônomo de programação não faz essa pausa. Se ele consegue formar solicitações a partir da documentação, inspecionar erros e tentar alternativas, qualquer operação recém-alcançável passa a fazer parte de sua autoridade prática.

## Os rótulos de versão não medem autoridade

Um número de versão descreve a promessa de compatibilidade do provedor da API, não a mudança de permissões experimentada pelo agente. Trate toda atualização de API como uma revisão de autoridade até comparar o que a credencial podia fazer antes e depois.

A especificação de Versionamento Semântico afirma que uma versão MAJOR muda quando ocorre uma alteração incompatível na API pública. Isso ajuda os mantenedores de bibliotecas a decidir se os chamadores podem deixar de funcionar. Não significa que uma versão MINOR não possa adicionar um novo endpoint administrativo, ampliar um filtro padrão ou aceitar um token de acesso destinado a outro público. As três mudanças podem preservar a compatibilidade e ainda aumentar o que um agente consegue fazer.

Essa distinção importa porque as equipes costumam fazer a pergunta errada: «Nosso código continuará funcionando?». A pergunta que protege a conta é: «Quais operações este agente existente consegue realizar com sucesso agora, contra quais recursos e com qual credencial?»

Uma atualização de API tem quatro superfícies separadas:

- Compatibilidade da solicitação: métodos, caminhos, parâmetros e formatos de payload.
- Alcance dos recursos: as contas, projetos, repositórios, arquivos ou registros que uma solicitação pode acessar.
- Alcance das ações: operações de leitura, gravação, exclusão, implantação, cobrança e identidade que podem ser concluídas.
- Aceitação de credenciais: quais tokens, chaves, assinaturas, públicos e escopos o provedor aceita.

Um teste bem-sucedido de compatibilidade da solicitação diz muito pouco sobre as outras três áreas. Por isso, uma alteração pode passar por uma suíte de regressão convencional e ainda dar a um agente uma nova rota até dados de produção.

Não presuma que uma versão de API com data resolva o problema. Um provedor pode manter estável uma superfície datada e, ao mesmo tempo, mudar um serviço de autenticação compartilhado, adicionar campos opcionais que o agente descobre ou alterar padrões fora do caminho do endpoint. Fixar uma versão é útil. Tratar essa fixação como um limite de permissões é descuidado.

## Crie o mapa de autoridade antes e depois

Você não consegue revisar uma atualização apenas com um changelog. Crie um mapa compacto das solicitações que o agente pode emitir e compare o comportamento observado nas versões antiga e nova.

Comece pelo tráfego real, não pelo desenho pretendido. Os agentes frequentemente usam mais endpoints do que a tarefa original sugere: chamadas de descoberta, novas tentativas após erros de validação, paginação, endpoints de consulta que convertem nomes em IDs e APIs convenientes sugeridas por mensagens de erro. Inclua essas chamadas, pois elas podem revelar identificadores de recursos ou abrir uma rota mais ampla do que a ação planejada.

Para cada família de solicitações, registre estes fatos:

| Campo | O que registrar |
|---|---|
| Operação | Método HTTP e caminho normalizado, como `POST /v2/projects/{id}/deployments` |
| Limite do recurso | O locatário, projeto, repositório, ambiente ou classe de registro que pode ser acessado |
| Credencial | Classe do token ou rótulo da chave de API, nunca o segredo em si |
| Condição de autorização | Escopo, função, público, concessão do usuário ou regra do servidor que permite a operação |
| Comportamento padrão | O que acontece quando filtros opcionais, limites de página e campos de destino não são informados |
| Expectativa de negação | O status e o erro esperados para recursos e ações proibidos |

O mapa deve indicar o limite do recurso em linguagem simples. «Pode chamar a API de implantações» é vago demais. «Pode criar implantações somente no projeto de sandbox» pode ser testado. Se o provedor não expõe detalhes suficientes para declarar esse limite, use uma identidade de teste separada para o agente até conseguir estabelecê-lo.

Depois, faça uma comparação em duas colunas. Execute o mesmo conjunto de solicitações nas versões antiga e nova com uma conta isolada que contenha recursos deliberadamente separados: pelo menos um projeto permitido, um projeto proibido, um registro inativo e uma conta de outro locatário, se o serviço oferecer suporte a locatários. Os dados de teste precisam ter nomes reconhecíveis para que você identifique qualquer vazamento acidental nos resultados.

Não compare apenas códigos de status. Uma resposta `200` pode esconder a diferença importante: o dobro de registros, um novo link `next_page` que atravessa um limite, um campo adicional de credencial ou um identificador de objeto que permite ao agente chamar um endpoint privilegiado mais tarde. Compare o formato e os identificadores da resposta e examine os novos campos em busca de autoridade posterior.

## Padrões alterados criam caminhos de acesso que ninguém solicitou

Um parâmetro omitido ainda é uma decisão de autorização quando o servidor escolhe seu significado. Padrões alterados merecem a mesma revisão que um novo endpoint de gravação.

A falha conhecida começa com uma solicitação de listagem aparentemente inofensiva. A versão um exige `project_id` e devolve apenas registros ativos. A versão dois permite a solicitação sem `project_id`, e o provedor define a omissão como «todos os projetos visíveis para este token». O código-fonte do agente não mudou se ele já omitia esse campo opcional. O alcance dos dados mudou.

Outros padrões produzem o mesmo resultado:

- Um endpoint de listagem passa a incluir objetos arquivados, excluídos ou herdados.
- A paginação muda de um conjunto pequeno e fixo de resultados para uma travessia por cursor com um `next` URL.
- Um endpoint de criação escolhe o espaço de trabalho padrão do chamador em vez de rejeitar um ID de espaço de trabalho ausente.
- Um endpoint de atualização aceita campos omitidos como «preservar o valor atual», em vez de exigir uma versão de concorrência explícita.
- Um endpoint de pesquisa começa a indexar conteúdo de serviços conectados.

Os provedores chamam isso de melhoria porque reduz o trabalho do cliente. Para um agente, menos trabalho do cliente muitas vezes significa menos atrito antes que uma ação alcance um alvo mais amplo.

Revise os padrões com solicitações deliberadamente incompletas. Para cada parâmetro opcional, envie uma solicitação sem o parâmetro, com um valor vazio se a API permitir e com um valor seguro explícito. Compare o conjunto de alvos e o erro do servidor. Um agente que gera solicitações tentará naturalmente omitir campos, especialmente depois de ver um exemplo de documentação que não os inclui.

Não dependa de um texto no prompt, como «use somente o projeto A», para conter isso. As instruções do prompt influenciam a escolha da solicitação, mas a API decide se uma solicitação pode acessar o projeto B. Coloque o limite do projeto na credencial, no desenho do endpoint ou em um gateway que valide a solicitação antes que ela saia da máquina.

## Novos endpoints tornam credenciais amplas ainda mais amplas

Um novo endpoint altera a autoridade de uma credencial existente se essa credencial puder se autenticar nele. O agente não precisa ter chamado o endpoint antes da atualização para que o risco exista.

As equipes costumam excluir endpoints adicionados da revisão porque os chamam de «nova funcionalidade». Essa lógica funciona quando uma pessoa recebe um novo controle na interface e um administrador concede o acesso separadamente. Ela falha quando um token bearer com escopo amplo funciona automaticamente na nova rota.

Imagine que um agente tenha um token descrito como `projects:write`. Na versão um, esse token pode criar e editar metadados de projetos. A versão dois adiciona `POST /projects/{id}/exports`, que cria uma exportação para download e usa o mesmo escopo. A string do escopo não mudou, mas o efeito de possuí-la mudou. O agente pode descobrir esse endpoint por meio de um esquema de API, um cliente gerado, uma dica de erro ou a documentação comum.

Classifique novos endpoints pelo efeito, não pelo verbo HTTP. Endpoints `GET` podem expor código-fonte, valores secretos, histórico de auditoria, dados pessoais ou URLs de download assinadas. Endpoints `POST` podem criar custos irreversíveis ou disparar fluxos de trabalho externos. Uma rota `DELETE` pode ser menos perigosa que uma rota `GET` que revela uma credencial utilizável em outro lugar.

Revise cada nova rota com quatro perguntas:

1. Uma credencial de agente existente se autentica com sucesso?
2. Quais escopos, funções ou classes de chave de API existentes permitem seu uso?
3. A saída pode fornecer identificadores, URLs ou tokens para outra operação?
4. O agente pode alcançá-la pela biblioteca cliente, pelo documento de descoberta ou pela documentação fornecida?

A última pergunta identifica uma recomendação ruim comum: «Não vamos informar o novo endpoint ao agente». A restrição parece prática porque os agentes seguem seu contexto de trabalho na maior parte do tempo. Ela não é um controle. Agentes podem inspecionar esquemas, inferir caminhos convencionais ou receber instruções de uma tarefa posterior. O servidor deve rejeitar uma operação não aprovada mesmo quando o cliente conhece sua URL exata.

Se o provedor não consegue separar a nova rota de um escopo antigo e amplo, crie uma identidade de integração mais restrita antes da atualização. Um token destinado a um fluxo estreito não deve herdar todos os significados futuros que um provedor atribuir a um nome de escopo amigável.

## Mudanças na autenticação são mudanças de permissão

O comportamento de autenticação pertence à revisão da atualização porque aceitar uma credencial de outra maneira muda quem pode agir. As equipes frequentemente testam o login bem-sucedido e ignoram os casos de negação, justamente onde uma atualização pode causar danos.

O OAuth 2.0 define tokens de acesso como credenciais que representam uma concessão de autorização, enquanto a RFC 9700, OAuth 2.0 Security Best Current Practice, recomenda a correspondência exata de URIs de redirecionamento e descreve proteções contra reutilização de tokens e tokens vinculados ao emissor. A lição prática é mais ampla que o OAuth: o formato de um token, sozinho, não estabelece seu destinatário, emissor ou escopo pretendido. O servidor de recursos precisa aplicar essas propriedades em toda solicitação aceita.

Mudanças de versão costumam tocar essa aplicação indiretamente. Um provedor pode introduzir um novo emissor, aceitar tokens destinados a uma API irmã, adicionar uma rota de troca de tokens, alterar a rotação de tokens de atualização ou permitir uma chave de API legada junto com um token com escopo. A pressão por compatibilidade torna essas mudanças tentadoras. Ela também cria caminhos alternativos que os engenheiros esquecem de testar.

Teste aceitação e rejeição. Para cada classe de credencial, tente a operação permitida, a mesma operação contra um recurso proibido, uma credencial expirada, um token com público incorreto, um token sem o escopo necessário e uma credencial revogada. Se o provedor oferecer tokens de atualização, teste se uma atualização preserva a concessão antiga, muda seu público ou ganha silenciosamente os escopos concedidos durante um fluxo posterior de consentimento.

Um registro útil tem esta aparência:

```text
credential: build-agent-sandbox
request: POST /v3/projects/prod-42/deployments
expected: 403 forbidden
old version: 403 {"error":"insufficient_scope"}
new version: 201 {"id":"dep_...","environment":"production"}
review result: block upgrade and revoke credential
```

O corpo da resposta importa. Um `403` que vira `404` pode ser uma mudança intencional para ocultar informações. Um `403` que vira `201` é um aumento de autoridade, mesmo que o changelog o chame de compatibilidade aprimorada.

Examine também o comportamento dos cabeçalhos. Cabeçalhos personalizados podem selecionar uma versão da API, uma organização ou um usuário personificado. Se a nova API tratar um cabeçalho ausente como a organização padrão, uma nova tentativa do agente depois de um erro de formatação do cabeçalho pode cair no lugar errado. Registre os cabeçalhos exatos nos testes, com os segredos ocultos, e teste a omissão separadamente.

## O comportamento do agente transforma pequenas diferenças em fluxos completos

Um agente pode encadear chamadas individualmente comuns e produzir um resultado que o projetista da API nunca analisou como uma única permissão. A revisão da versão precisa acompanhar esses encadeamentos.

Um novo campo de listagem pode revelar o ID de um repositório. Esse ID pode alimentar um endpoint de download. A resposta do download pode incluir uma URL assinada. A URL pode expor um artefato cuja configuração contém outro endpoint de serviço. Cada chamada pode parecer permitida por si só. A sequência combinada pode ultrapassar a tarefa recebida pelo agente.

Por isso, a revisão de autorização endpoint por endpoint é necessária, mas incompleta. Adicione testes de fluxo para as ações que você quer que o agente realize e para ações próximas que deseja excluir. Acompanhe o fluxo de identificadores entre chamadas: IDs, cursores de paginação, locais, URLs pré-assinadas, IDs de tarefas e mensagens de erro que revelam nomes válidos de recursos.

Mantenha os testes concretos. Se o agente deve atualizar um problema em um repositório, teste se ele consegue:

- Ler o problema pretendido e atualizar seus campos permitidos.
- Falhar ao tentar usar o ID de um problema de outro repositório.
- Falhar ao tentar alterar configurações ou webhooks do repositório.
- Falhar ao seguir um link para uma rota de exportação, lista de membros ou gerenciamento de tokens.

O caminho de falha importa tanto quanto o caminho de sucesso. Um agente trata erros como informação. Uma negação detalhada que menciona outro endpoint pode facilitar a descoberta de uma rota não intencional. Talvez você aceite essa troca para desenvolvedores humanos, mas precisa saber que ela existe antes de expor a integração a um processo autônomo.

Limite as novas tentativas durante os testes de atualização. Uma política de repetição que era inofensiva quando uma solicitação era idempotente pode criar ações duplicadas se a nova versão mudar o tratamento de idempotência ou devolver um timeout depois de concluir o trabalho. Verifique se a API usa uma chave de idempotência, por quanto tempo mantém essa chave e se a atualização muda o nome do cabeçalho ou as regras de hash da solicitação.

## Uma diferença de capacidades identifica mudanças que os testes comuns não veem

Uma diferença de capacidades é um teste repetível que pergunta quais solicitações uma credencial consegue concluir, e não se a aplicação ainda recebe os dados esperados. Mantenha-o pequeno o suficiente para ser executado a cada candidato de versão.

Crie um conjunto de solicitações em um repositório que não contenha segredos de produção. Use variáveis de ambiente para os tokens de teste e direcione tudo a uma conta descartável. O padrão de shell abaixo registra as partes que revelam mudanças de autoridade sem exibir credenciais:

```sh
curl -sS -D headers.txt -o body.json \
  -H "Authorization: Bearer $TEST_TOKEN" \
  -H "X-API-Version: 2025-01-01" \
  "https://api.example.test/v1/projects?limit=2"

printf 'status: ' && head -n 1 headers.txt
printf 'headers:\n' && grep -Ei '^(link|location|x-request-id|www-authenticate):' headers.txt
printf 'identifiers:\n' && jq -r '.. | objects | (.id? // empty)' body.json | sort -u
```

Execute o conjunto uma vez para cada versão e compare status, cabeçalhos selecionados e identificadores normalizados. Não faça uma comparação cega do JSON completo. Horários, IDs de solicitação e ordenação criam ruído e treinam os revisores a ignorar diferenças. Normalize esses campos primeiro, mas preserve links de paginação, IDs de recursos, nomes de funções e qualquer campo que possa direcionar uma solicitação posterior.

Seu conjunto deve incluir solicitações bem-sucedidas, negações esperadas, parâmetros opcionais omitidos e a primeira página seguida de uma chamada de paginação. Adicione uma solicitação para cada rota recém-documentada que pareça relacionada a um escopo existente do agente. O objetivo não é enumerar todo o provedor. É cobrir cada operação que o agente possa descobrir ou combinar de maneira realista.

Um arquivo simples de resultados torna as decisões revisáveis:

```json
{
  "case": "forbidden-production-deploy",
  "credential": "build-agent-sandbox",
  "request": "POST /v3/projects/prod-42/deployments",
  "expected_status": 403,
  "observed_status": 403,
  "observed_resource_ids": [],
  "version": "2025-01-01"
}
```

Exija uma decisão explícita do revisor para cada diferença. «Esperado porque o provedor mudou» não é uma decisão. O revisor precisa declarar se o novo comportamento continua dentro da autoridade aprovada do agente e, em caso afirmativo, onde essa autoridade é aplicada.

## Os registros mostram o que aconteceu, não o que deveria ter acontecido

Os registros de solicitações ajudam a investigar uma atualização, mas não substituem uma revisão de autoridade antes da implantação. Eles respondem a perguntas diferentes.

Antes da atualização, a diferença de capacidades informa se o provedor aceitará uma solicitação indesejada. Depois da atualização, os registros mostram se o agente realmente tentou fazê-la, qual processo iniciou a tentativa e se é preciso conter a conta. Você precisa das duas coisas porque uma solicitação negada hoje pode ser aceita amanhã após uma mudança de comportamento do provedor.

Registre o seletor de versão, a operação normalizada, o limite do alvo, o rótulo da credencial, a decisão, o status e o ID de correlação. Não registre tokens bearer, cabeçalhos de autorização brutos, corpos completos de solicitações ou campos de resposta que contenham segredos. Um registro de segurança que armazena a credencial que deveria proteger apenas transfere a violação.

Separe o registro da sessão do registro da ação. A sessão informa qual processo de agente recebeu permissão para operar durante uma execução. O registro da ação informa qual solicitação individual ele fez. Essa distinção se torna importante quando um agente de longa duração começa com uma versão revisada e depois recebe uma mudança de ambiente ou uma biblioteca cliente regenerada.

O Sallyport mantém um diário de sessões e um diário de atividades projetados a partir de um único registro de auditoria criptografado e encadeado por hash, para que uma pessoa operadora possa inspecionar tanto a execução do agente quanto cada ação HTTP ou SSH. Sua verificação offline `sp audit verify` confirma a cadeia sem acesso ao cofre, o que é útil quando uma revisão de atualização se transforma em uma investigação de incidente.

Não confunda evidência de adulteração com prevenção. Um registro de auditoria íntegro pode provar que um novo endpoint foi usado. Ele não consegue recuperar dados exportados de um serviço remoto. Mantenha ações sensíveis atrás de credenciais e aprovações que falhem antes que a solicitação saia da máquina.

## A aprovação precisa estar vinculada a um processo, não a uma tarefa vaga

Uma aprovação humana só consegue impedir uma atualização não revisada se informar qual executável está pedindo autoridade. «O agente quer acesso à API» é informação insuficiente quando vários processos locais podem falar o mesmo protocolo.

Vincule a autorização da sessão à autoridade de assinatura de código do processo solicitante quando o sistema operacional a expuser. Isso identifica uma falha comum de substituição: um agente confiável inicia uma sessão e depois um auxiliar não confiável ou um binário copiado tenta reutilizar o mesmo caminho de credencial. A identidade do processo não prova que toda solicitação futura será sensata, mas oferece à pessoa operadora um objeto concreto para aprovar ou revogar.

Reserve a aprovação por chamada para credenciais cujo efeito seja difícil de restringir, como implantação em produção, administração de contas ou exportação de dados. Exigir que alguém aprove cada leitura inofensiva apenas treina a pessoa a clicar nos cartões. A fadiga de aprovação é um erro de projeto, não uma falha do usuário.

O Sallyport usa uma escada fixa de três controles: o cofre bloqueado nega todas as ações, um novo processo de agente solicita autorização de sessão por padrão e uma configuração por chave pode exigir uma aprovação separada a cada uso. Esse modelo restrito não expressa todas as regras organizacionais, mas evita esconder mudanças de autoridade em um conjunto de sintaxes de políticas.

Quando uma atualização de API muda o escopo efetivo de uma credencial, revogue a sessão atual e exija uma nova aprovação depois da revisão. Não deixe uma sessão aprovada para os endpoints de ontem continuar silenciosamente ativa nos endpoints mais amplos de amanhã.

## Transforme a revisão de autoridade em um bloqueio de lançamento

Uma atualização de versão da API deve falhar no bloqueio de lançamento quando uma credencial atual ganha uma solicitação bem-sucedida sem explicação, uma solicitação negada passa a ser permitida ou uma resposta expõe um novo identificador que possibilita um fluxo proibido.

Inclua a revisão no mesmo registro de mudança das atualizações de dependências e alterações no cliente gerado. Registre os seletores antigo e novo da API, as notas de versão do provedor, a saída da diferença de capacidades, as classes de credenciais testadas e a pessoa que aceitou cada diferença intencional. É um trabalho rotineiro, por isso costuma ser ignorado até a primeira entrada estranha no registro de auditoria.

Não espere por uma versão major da API. Inicie a revisão quando o provedor mudar uma versão de API, o serviço de autenticação, as configurações do aplicativo OAuth, o SDK gerado, o esquema de descoberta, um cabeçalho padrão ou a definição de um escopo. Uma mudança fora da URL ainda pode alterar a decisão tomada pelo servidor remoto.

Comece pela credencial que causaria mais dano se ganhasse uma rota extra. Dê a ela uma conta de teste isolada, escreva cinco solicitações permitidas e negadas e execute-as contra a versão proposta. Se você não consegue explicar por que cada sucesso pertence ao trabalho do agente, a integração não está pronta para uso autônomo.