Como funciona a atribuição de contas de API compartilhadas entre sessões de agentes

Uma conta de API compartilhada às vezes é a escolha operacional certa. Os fornecedores podem emitir um único token da organização, os limites de uso podem pertencer a essa conta, e substituí-la por várias chaves quase idênticas pode criar mais segredos sem melhorar o controle.

O erro está em tratar essa conta como um agente. Ela é uma entidade de credencial externa, ou seja, a identidade reconhecida pelo fornecedor. Quando vários agentes locais a utilizam, você precisa de um segundo registro que indique qual processo local fez cada solicitação, qual trabalho ele estava autorizado a realizar e como obteve autorização para usar a credencial. Se esse registro não for coletado no momento da execução, você terá de adivinhar depois.

Isso é menos chamativo do que dar um nome e um painel colorido a cada agente. Também é o que continua funcionando quando dois agentes competem, um deles tenta novamente, uma pessoa revoga uma execução no meio do caminho e a página de auditoria do fornecedor mostra apenas automation-service.

Uma conta do fornecedor e um agente são identidades diferentes

Uma conta compartilhada do fornecedor responde: «Qual credencial o provedor aceitou?» A atribuição do agente responde: «Qual principal local causou esta operação específica?» As respostas costumam ser diferentes, e forçá-las no mesmo campo produz trilhas de auditoria ruins.

Mantenha pelo menos quatro identidades distintas:

• Conta externa: o tenant do fornecedor, usuário de serviço, cliente OAuth ou identidade da chave de API visível para a API remota.
• Sessão de execução: um processo de agente iniciado, com um ID de sessão novo e impossível de adivinhar.
• Principal iniciador: a pessoa, o job de CI ou o serviço pai que iniciou a sessão.
• Referência do trabalho: o issue, a solicitação de mudança, a implantação, o repositório ou a tarefa explícita que explica por que a chamada foi feita.

A conta externa pode permanecer estável por meses. A sessão de execução não deve permanecer. Uma referência de tarefa pode se repetir em várias sessões. O iniciador pode ser uma pessoa diante do teclado em um dia e um build automatizado no seguinte. Cada campo tem uma duração diferente e responde a uma pergunta diferente.

Essa distinção não é apenas uma questão de terminologia. Suponha que vendor-prod exclua uma implantação remota. O fornecedor pode afirmar corretamente que vendor-prod fez a exclusão. Seu registro local precisa mostrar se a sessão s_7f3... veio de um agente de release iniciado por Maya, se tinha aprovação para aquela execução e se a exclusão foi uma chamada direta ou uma repetição após um timeout. Um único campo actor=vendor-prod oculta todos os fatos que poderiam mudar a resposta ao incidente.

A RFC 8693 faz uma distinção relacionada na delegação OAuth. Ela separa o sujeito em nome de quem a autoridade existe do agente atual que usa a declaração JWT act. Também afirma que os servidores de recursos devem tomar decisões de acesso com base nas declarações de nível superior do token e no agente atual, não em agentes históricos aninhados. Esse é um limite útil também para sistemas locais de agentes: mantenha a linhagem para investigação, mas tome decisões de autorização com base em uma identidade clara da sessão atual, não em uma história longa e ambígua de chamadas anteriores.

Não chame uma conta do fornecedor de «o agente». A conta pode ser usada por agentes, scripts, operadores de emergência e jobs de migração. Dê a ela um nome preciso, como external_principal, e faça da sessão local o agente no seu próprio registro de auditoria.

A identidade da sessão deve vir do iniciador

O processo que inicia um agente deve criar a identidade da sessão antes que o agente possa solicitar uma ação externa. Não deixe o agente escolhê-la. Um agente que pode selecionar session_id=release-approved consegue tornar uma revisão posterior deliberadamente enganosa.

Um registro de sessão prático contém material suficiente para identificar o executável e contexto suficiente para explicar o trabalho:

{
  "session_id": "ses_01JQ6EXAMPLE3K5A",
  "started_at": "2026-07-22T15:04:18Z",
  "initiator": {
    "kind": "human",
    "id": "[email protected]"
  },
  "agent": {
    "process_id": 48192,
    "binary_authority": "signed-local-agent",
    "launch_path": "/workspace/payments"
  },
  "work": {
    "kind": "change_request",
    "id": "CR-1842"
  },
  "parent_session_id": null
}

Os nomes exatos dos campos importam menos do que a responsabilidade por eles. O iniciador controla session_id, o horário de início, a identidade do executável e a sessão pai. Uma pessoa ou o sistema chamador fornece a referência do trabalho, mas o gateway deve registrar quem a forneceu. O agente pode propor uma descrição da tarefa, mas esse texto nunca deve substituir a identidade fornecida pelo iniciador.

Os IDs de processo, sozinhos, são evidências fracas. Os sistemas operacionais os reutilizam, os logs sobrevivem aos processos e um ID de processo diz pouco sobre quem iniciou o binário. A autoridade de assinatura do código é mais útil em uma máquina local de desenvolvimento, porque associa a decisão de aprovação à família de processos assinados. Mesmo assim, registre o caminho do executável e o contexto de inicialização quando estiverem disponíveis. Uma assinatura conhecida não prova que todas as execuções tiveram o mesmo objetivo.

Use uma nova sessão para cada novo processo de agente. Reutilizar uma sessão porque o número da tarefa é o mesmo transforma uma aprovação para um experimento curto em um pacote de permissões duradouro. Agentes de longa duração exigem uma decisão explícita de política: manter uma sessão e tornar sua duração visível, ou alternar a sessão em um limite definido, como uma nova solicitação de pull ou a retomada de uma execução no terminal. Não faça as duas coisas silenciosamente.

A atribuição deve ser capturada antes da injeção da credencial

O lugar mais seguro para associar um agente a uma solicitação é imediatamente antes de um componente confiável aplicar a credencial compartilhada e enviar a solicitação. Qualquer coisa anterior pode ser alterada pelo agente. Qualquer coisa posterior pode não existir, ser resumida ou ser sobrescrita pelo fornecedor.

Crie um envelope de chamada que o agente não possa preencher completamente. O agente fornece a ação solicitada. O gateway acrescenta a identidade da sessão, a decisão de autorização, o ID da chamada e a referência da credencial externa. Armazene o envelope antes de transmitir a solicitação e acrescente o resultado quando ele retornar.

{
  "call_id": "call_01JQ6F9K4W7D",
  "session_id": "ses_01JQ6EXAMPLE3K5A",
  "external_principal": "vendor-prod",
  "channel": "http",
  "request": {
    "method": "POST",
    "host": "api.vendor.example",
    "path_template": "/v1/deployments/{id}",
    "operation": "create_deployment"
  },
  "authorization": {
    "vault_unlocked": true,
    "session_authorized": true,
    "per_call_approval": false
  },
  "work_id": "CR-1842",
  "attempt": 1,
  "created_at": "2026-07-22T15:08:34Z"
}

Observe o que está ausente: o bearer token, o corpo completo da solicitação e uma afirmação livre de que o agente é confiável. Um log que armazena segredos para provar atribuição falhou em sua primeira tarefa. Um log que registra cada byte de um corpo também pode expor dados de clientes, código-fonte ou registros regulamentados. Capture um nome de operação normalizado, um modelo de rota, identificadores não secretos selecionados e um resumo criptográfico do conteúdo quando o próprio payload for relevante para uma revisão.

Esse desenho também separa intenção de efeito. Um agente pode solicitar create_deployment, mas o serviço remoto pode retornar um erro de validação. O diário de chamadas deve preservar os dois fatos. Depois, você poderá responder se o agente tentou realizar a ação sem afirmar que ela teve sucesso.

O Sallyport segue essa disposição: o agente se conecta por meio de seu shim MCP, enquanto o aplicativo mantém o segredo e executa a ação HTTP ou SSH. Assim, os registros resultantes de sessão e atividade podem associar uma execução local ao uso de uma credencial compartilhada sem colocar a credencial no contexto do agente.

Cabeçalhos fornecidos pelo agente são evidência, não prova

As equipes costumam adicionar cabeçalhos como X-Agent-Name, X-Task-ID ou X-Run-ID e considerar o problema resolvido. Esses campos podem ajudar a correlacionar logs remotos, mas um agente que controla a solicitação também pode omiti-los, alterá-los ou reproduzi-los. São rótulos, não uma fronteira de autoridade.

Você pode encaminhar cabeçalhos de atribuição quando o fornecedor os aceitar, desde que o gateway siga três regras. Primeiro, remova versões fornecidas pelo agente de cabeçalhos reservados. Segundo, gere os valores finais a partir da sessão registrada e do envelope da chamada. Terceiro, trate o recebimento do cabeçalho pelo fornecedor como evidência complementar, não como sua fonte de verdade.

Por exemplo, reserve este pequeno conjunto de cabeçalhos dentro do gateway:

X-Execution-Session: ses_01JQ6EXAMPLE3K5A
X-Action-Call: call_01JQ6F9K4W7D
X-Work-Reference: CR-1842

Não coloque um endereço de e-mail, um prompt, um nome de branch com dados de clientes ou um comando bruto em um cabeçalho apenas por conveniência. Os cabeçalhos passam por proxies, sistemas de rastreamento, relatórios de erro e ferramentas de suporte do fornecedor. Use IDs opacos e depois consulte-os no seu diário local protegido.

Alguns provedores rejeitam cabeçalhos desconhecidos, removem-nos ou não os exibem nas telas de auditoria. Isso é normal. A API remota não precisa se tornar seu sistema de identidade. Seu gateway deve funcionar mesmo quando o provedor aceita apenas o esquema comum de autorização.

Existe outra armadilha: um cabeçalho assinado não substitui o registro local. Uma assinatura de solicitação pode provar que um gateway assinou alguma solicitação, mas não preserva a aprovação humana, a identidade do processo, o contexto da tarefa ou o resultado, a menos que você registre esses detalhes localmente. Assinaturas protegem declarações de transporte. Sozinhas, não criam um registro de investigação.

As repetições precisam de linhagem, não de um único horário

Agentes autônomos tentam novamente. Clientes HTTP tentam novamente. Comandos SSH podem ser executados de novo depois que um terminal desconectado retorna. Se sua trilha de auditoria gravar uma linha por ação pretendida, ela ocultará os mecanismos que causam alterações duplicadas. Se gravar apenas solicitações brutas, fará uma única ação pretendida parecer várias decisões sem relação.

Modele os dois níveis. Dê à operação pretendida um operation_id e a cada tentativa de rede um call_id separado. Associe as repetições à tentativa anterior e registre o motivo da repetição.

{
  "operation_id": "op_01JQ6F8P0Z",
  "call_id": "call_01JQ6F9K4W7D",
  "attempt": 2,
  "retries_call_id": "call_01JQ6F79S2M1",
  "retry_reason": "connection_closed_before_response",
  "idempotency_key": "idem_94c2e1",
  "vendor_request_id": "req_8d71"
}

O retry_reason importa. Uma resposta 429 significa que o fornecedor recebeu a primeira solicitação e a recusou por limitação de uso. Um timeout depois que os bytes saíram do gateway não informa se o fornecedor concluiu a ação. Esses casos exigem respostas operacionais diferentes e não devem ser reduzidos a failed.

Use chaves de idempotência para operações que criam ou alteram estado remoto quando o fornecedor oferecer suporte a elas. Gere a chave no gateway confiável ou faça o iniciador fornecê-la junto com o registro do trabalho. Não deixe um modelo criar uma chave nova sempre que revisar o próprio plano, pois isso elimina a capacidade de reconhecer uma operação reproduzida.

Uma falha comum ocorre assim. A sessão A pede a criação de uma implantação, a conexão cai e o cliente tenta novamente. A sessão B começa alguns instantes depois com a mesma referência de tarefa, não vê nenhuma implantação visível e faz o pedido de novo. Agora o fornecedor tem duas implantações. Um diário útil mostra duas sessões, duas operações pretendidas, suas tentativas individuais e qualquer chave de idempotência compartilhada. Um diário fraco mostra quatro linhas POST /deployments sob uma única conta de serviço e deixa a equipe reconstruir o restante a partir dos horários.

A aprovação deve estar associada a um processo, não a um nome amigável

Um prompt que pergunta «Permitir que o agente de release use produção?» parece razoável até existirem dois agentes de release, um iniciado a partir de um repositório confiável e outro de um diretório copiado. Um nome é texto de apresentação. A aprovação precisa estar associada à sessão de execução e à autoridade do processo que a criou.

A aprovação por sessão é um bom padrão para agentes que fazem várias chamadas relacionadas. Ela permite que o operador veja quem está solicitando e evita transformar uma tarefa curta em uma sequência de prompts idênticos. A aprovação deve expirar quando o processo terminar. Um novo processo, mesmo com o mesmo texto de tarefa, deve solicitar aprovação novamente.

Use aprovação por chamada para operações de alto impacto ou com escopo excepcionalmente amplo. Isso não substitui a aprovação da sessão. A pergunta é mais específica: este uso desta credencial deve prosseguir agora? Uma equipe que usa aprovação por chamada para toda leitura inofensiva ensinará as pessoas a aprovar sem ler. Isso é fadiga de aprovação por desenho, não uma falha humana.

Registre a decisão como um evento com uma referência estável:

{
  "approval_id": "apr_01JQ6G3C",
  "session_id": "ses_01JQ6EXAMPLE3K5A",
  "scope": "session",
  "decision": "approved",
  "decided_at": "2026-07-22T15:06:11Z",
  "process_authority": "signed-local-agent"
}

Não registre um booleano isolado em cada chamada e finja que isso prova consentimento. O booleano informa que existia uma aprovação. O evento de aprovação mostra quando ela ocorreu, o que abrangia e qual sessão autorizou. Se um operador revogar a sessão depois, preserve essa revogação como um novo evento. Excluir a aprovação antiga deixa o registro mais limpo e o incidente mais difícil de entender.

Os logs de auditoria do fornecedor devem corroborar seu registro

Os logs do fornecedor são úteis, mas normalmente descrevem o modelo de identidade do fornecedor, não o seu. Um token compartilhado pode aparecer como usuário de serviço, aplicativo OAuth, hash de token, instalação ou endereço IP. Isso pode ajudar a confirmar que uma chamada externa ocorreu, mas raramente informa qual sessão local de agente escolheu a ação.

A documentação do GitHub é um exemplo concreto dessa distinção. Chamadas feitas com um usuário de GitHub App para um token de servidor podem mostrar o usuário como agente da auditoria, identificando também o tipo de acesso programático como esse formato de token. Os eventos de auditoria empresarial do GitHub também expõem campos como agente, informações do token, ID da solicitação e user agent para muitos tipos de evento. Isso é uma evidência útil do lado do provedor, mas o significado desses campos pertence ao modelo de autorização do GitHub, não ao modelo local de sessões de agente.

Associe registros remotos e locais com correlacionadores estáveis sempre que possível:

• Salve o ID da solicitação do fornecedor retornado em um cabeçalho ou corpo de resposta.
• Salve seu ID de chamada de saída e um nome de operação normalizado.
• Registre o status da resposta, o horário de conclusão e identificadores seguros de recursos.
• Preserve o principal externo usado na chamada.
• Mantenha o ID da sessão local como a identidade de execução autoritativa.

Evite fazer associações principalmente pelo horário. Diferenças entre relógios, processamento assíncrono do fornecedor, repetições e filas tornam um horário próximo menos confiável do que parece. Os horários continuam úteis para restringir uma busca, mas não devem decidir a atribuição quando existe um ID de solicitação ou uma chave de idempotência.

Alguns fornecedores podem emitir tokens delegados de curta duração, tokens OAuth em nome de um usuário ou tokens de instalação de aplicativo. Use esses recursos quando eles derem ao provedor uma visibilidade significativa do agente e se encaixarem no seu modelo de privilégios. O GitHub, por exemplo, documenta a distinção entre um aplicativo agindo em nome de um usuário e outros tipos de acesso programático. Isso oferece uma atribuição melhor do lado do provedor do que um token estático compartilhado, mas não elimina a necessidade de identificar o processo local que iniciou a chamada.

Separe credenciais apenas quando elas criarem uma fronteira real

O conselho mais comum é «dê a cada agente sua própria chave de API». Ele é popular porque é fácil de explicar e faz a tela de auditoria do fornecedor parecer mais organizada. Nem sempre é o controle certo.

Credenciais separadas valem o custo operacional quando criam uma fronteira significativa. Pode ser a diferença de escopo entre um agente de descoberta somente leitura e um agente de implantação, a revogação independente no fornecedor, a cobrança separada ou um registro de auditoria do provedor que identifique o principal distinto. Se cada chave tem o mesmo escopo amplo, o mesmo responsável pela rotação e o mesmo caminho de execução local, você multiplicou o inventário de segredos mais do que melhorou a atribuição.

Faça este teste antes de criar outra identidade no fornecedor:

1. A nova credencial pode receber menos privilégios do que a compartilhada?
2. Você pode revogá-la sem interromper trabalhos não relacionados?
3. O provedor a registrará como um agente distinto de uma forma útil para quem responde a incidentes?
4. Você pode alternar e aposentar a credencial sem deixar cópias esquecidas nas ferramentas locais?
5. Ela remove uma decisão de autorização significativa do gateway local?

Se a resposta for negativa para a maioria dessas perguntas, mantenha a conta externa compartilhada e melhore o registro do agente local. Essa abordagem fornece aos responsáveis pela resposta os detalhes de que realmente precisam: qual sessão de agente fez a chamada, sob cuja iniciativa, para qual item de trabalho, com qual aprovação e com qual resultado.

Há um limite para esse argumento. Se uma credencial concede administração de produção e um agente experimental não precisa desse poder, não a compartilhe apenas porque seus logs são excelentes. A atribuição explica uma ação depois que ela ocorreu. Os limites de escopo determinam quais ações podem ocorrer.

Um diário com evidência de adulteração deve preservar a ordem e as recusas

Um registro de auditoria que armazena apenas chamadas bem-sucedidas do fornecedor conta uma história incompleta. Chamadas negadas, tentativas com o cofre bloqueado, aprovações rejeitadas e sessões revogadas muitas vezes explicam por que um incidente não piorou. Elas também revelam um agente que continuou solicitando uma ação depois de perder autoridade.

Grave um evento quando a sessão começar, quando ocorrer uma decisão de autorização, quando uma chamada for preparada, quando a ação externa terminar e quando uma sessão for revogada ou encerrada. Associe os registros por IDs, em vez de copiar um objeto grande e mutável em cada linha. A cadeia deve tornar a sequência visível sem obrigar cada consumidor a reconstruir o estado a partir de prosa.

A evidência de adulteração importa porque a atribuição local costuma ser a única fonte que distingue agentes simultâneos usando a mesma conta do fornecedor. Se uma pessoa com acesso local puder alterar um registro de chamada depois de um incidente, a equipe terá recriado o mesmo problema de confiança um nível mais perto de casa. Logs encadeados por hash ajudam os revisores a detectar alterações, mas não decidem quais campos registrar. Você ainda precisa de um modelo completo de eventos.

O Sallyport projeta seus registros de Sessões e Atividades a partir de um único log de auditoria criptografado e encadeado por hash, e pode verificar essa cadeia offline com sp audit verify. O ponto operacional importante não é o nome do comando. É que uma aprovação de sessão, uma ação individual e uma revogação posterior podem ser verificadas no mesmo registro ordenado.

Não use o rótulo de uma conta do fornecedor como resposta final quando um revisor de incidentes perguntar quem fez algo. Siga o registro do principal externo até o ID da chamada, do ID da chamada até a sessão de execução, da sessão até o iniciador e a aprovação, e da resposta até o identificador de solicitação do próprio fornecedor. Se algum desses vínculos estiver faltando, corrija esse ponto de captura antes que a próxima credencial compartilhada se transforme em um mistério.