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

  1. Envie work_execute com a operação, o payload e mode: "preview".
  2. Apresente ao usuário a organização, o recurso, os argumentos e o impacto.
  3. Se houver aprovação, envie o mesmo payload com mode: "commit" e o confirmationToken retornado.
  4. 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:

{
  "operation": "archive_issue",
  "mode": "preview",
  "input": {
    "organizationId": "UUID_DA_ORGANIZACAO",
    "issueId": "UUID_DA_ISSUE"
  }
}

O commit usa o token recebido, sem mudar os argumentos:

{
  "operation": "archive_issue",
  "mode": "commit",
  "input": {
    "organizationId": "UUID_DA_ORGANIZACAO",
    "issueId": "UUID_DA_ISSUE"
  },
  "confirmationToken": "TOKEN_RETORNADO_PELA_PREVIA"
}

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.

Veja a demonstração de interface com AI Elements.