Quando o servidor pede confirmação
O catálogo marca operações destrutivas, administrativas ou irreversíveis como sensíveis. Exemplos incluem gerenciar workspaces, alterar membros e arquivar ou excluir issues. Uma execução sem commit retorna a prévia assinada para essas operações.
Nem toda escrita é automaticamente marcada como sensível. Consulte as capacidades e o contrato da operação. A interface pode pedir consentimento adicional, mas um botão visual não substitui a validação do servidor.
Fluxo em duas etapas
- Envie
work_executecom a operação, o payload emode: "preview". - Apresente ao usuário a organização, o recurso, os argumentos e o impacto.
- Se houver aprovação, envie o mesmo payload com
mode: "commit"e oconfirmationTokenretornado. - Apresente o resultado real da execução; uma aprovação não é confirmação de que a API já executou a alteração.
Exemplo de prévia, com identificadores ilustrativos:
O commit usa o token recebido, sem mudar os argumentos:
Vinculação e validade
O token é assinado e vinculado ao usuário, organização, operação e hash canônico do payload. O padrão atual expira em cinco minutos; use o expiresAt retornado como referência. Alterar o recurso ou o payload exige gerar outra prévia.
confirmation_expired, confirmation_mismatch e invalid_confirmation indicam que a confirmação não pode ser usada. confirmation_not_configured requer ajuste do segredo no servidor. Não remova a etapa de verificação para contornar esses erros.