Waafir
Esta página é uma tradução automática pendente de revisão humana. Pode conter erros.

Tokens de acesso pessoal

Um token de acesso pessoal (PAT) é uma credencial que você mesmo cria e cola. Ele serve para a API REST do Waafir e para scripts, e para um assistente de IA que não consegue fazer login: a maioria dos assistentes se conecta colando a URL do Waafir e fazendo login, sem nenhum token. Nos servidores MCP do Waafir, toda requisição leva ou uma conexão criada por login ou um PAT válido. Não há acesso anônimo, e uma sessão comum de navegador com login não é aceita nesta superfície (uma requisição autenticada por sessão é rejeitada). Um PAT age como você, dentro da sua organização, limitado pelo escopo e pelas salas de dados que você escolhe ao emiti-lo.

Onde emitir um token

Abra Complementos → Configuração → Tokens API. A página tem três partes: um formulário para emitir um novo token, a lista dos seus tokens existentes (com uma ação de revogar) e um snippet de configuração pronto para uso para conectar um assistente com um token.

Para emitir um token, preencha o formulário:

  • Nome — um rótulo legível para você reconhecer o token depois (por exemplo, "Claude Desktop – laptop"). Obrigatório.
  • Escopo — o que o token pode fazer. Veja abaixo.
  • Escopo de salas de dados — deixe Todas as salas de dados marcado para permitir que o token acesse todas as salas de dados às quais você tem acesso, ou desmarque e selecione salas de dados específicas para restringir o token apenas a elas.
  • Expiração — a data após a qual o token deixa de funcionar. Opcional de preencher, mas não opcional na prática: deixe em branco e o token é emitido com expiração de 90 dias. Veja Expiração.

Escopos

Um token carrega um de três escopos, em ordem crescente de autoridade:

EscopoPermiteUso típico
readListar e ler — salas de dados, pastas, arquivos, metadados de arquivos, pesquisa, URLs de download e visualização de permissões; ler o texto extraído de um documento; ler as conversas de Q&A dos investidores; verificar o status de um trabalho de tarjamento, tradução ou assinatura eletrônica.Um assistente somente leitura que responde a perguntas sobre uma sala de dados.
writeTudo o que read permite, mais alterações: criar, renomear, mover, excluir e restaurar pastas; enviar, renomear, mover, excluir e restaurar arquivos, incluindo enviar uma nova versão de um arquivo e reverter uma; iniciar o tarjamento ou a tradução de um documento; e criar, enviar, recusar e anular envelopes de assinatura eletrônica. Enviar um envelope (ou adicionar signatários a um já enviado) também exige Enviar para pessoas fora da sua organização, e seu assistente pede sua confirmação antes de enviar. Assinar (esign_sign) também exige Assinar documentos e, da mesma forma, é confirmado antes.Um assistente que organiza ou mantém uma sala de dados.
adminTudo o que write permite, mais as quatro ferramentas que concedem permissões: conceder ou revogar o acesso de um usuário a arquivos e salas de dados. Observe que as três ferramentas de leitura de permissões exigem apenas read.Um assistente que gerencia quem pode ver o quê.

O escopo é cumulativo — um escopo mais alto inclui tudo o que está abaixo dele. A referência de ferramentas de cada servidor informa o escopo mínimo que cada ferramenta exige.

Quem pode emitir cada escopo

Um token nunca pode carregar mais autoridade do que a pessoa que o emite:

  • read e write podem ser emitidos por qualquer membro ativo da sua organização.
  • admin só pode ser emitido por um proprietário ou administrador da organização. Se você não é proprietário nem administrador, a opção admin não aparece no seletor de escopo.
  • Investidores (e outras funções que não fazem parte da equipe da transação) não podem emitir tokens.

Além da emissão, as ferramentas de permissão admin aplicam um segundo limite no momento da chamada: o próprio dono do token precisa ser administrador ou gestor na organização para que uma concessão de permissão seja bem-sucedida. O escopo de um token é o limite do token; a função do dono é o limite da pessoa, e uma ação de administração precisa atender a ambos — exatamente a regra que a interface do produto aplica. Não há caminho mais permissivo pelo MCP do que pelo produto.

Permitir que um token assine documentos

Assinar exige um token com Assinar documentos ativado. Você escolhe isso ao criar o token em Complementos → Configuração, para um token write ou admin, de modo que apenas um assistente em que você confia possa assinar por você. A criação de um token já pede seu código de dois fatores quando você tem a autenticação de dois fatores ativada, então essa verificação cobre todas as assinaturas que o token fizer. A lista de tokens mostra Pode assinar em cada um desses tokens.

Seu assistente mostra primeiro os documentos, o signatário e os campos, e só assina quando você confirma. Um token sem Assinar documentos não vê esign_sign na sua lista de ferramentas e é recusado se a chamar. Tokens criados antes de esta opção existir não podem assinar: crie um novo com Assinar documentos ativado.

Permitir que um token leia o conteúdo de documentos

Ler um documento por inteiro, ou fazer perguntas à IA sobre documentos, exige um token com Ler conteúdo do documento ativado. Você escolhe isso ao criar o token em Complementos → Configuração, em qualquer escopo. A lista de tokens mostra Conteúdo do documento em cada um desses tokens. Isso abrange:

  • get_file_text, o texto extraído completo de um documento;
  • get_file_download_url, um link para baixar um arquivo;
  • esign_download_signed, um PDF de assinatura eletrônica assinado;
  • o link de download que translate_file_status retorna para uma tradução concluída;
  • GET /api/v1/files/{fileId}/content, os bytes do documento pela API REST;
  • POST /api/viewer/token, POST /api/viewer/artifact-access e POST /api/viewer/artifact-access/unlock, que geram o token ou cookie do visualizador com o qual o visualizador de documentos do produto transmite um documento;
  • as ferramentas de IA cuja pergunta ou entrada você escreve, já que uma resposta pode repetir o que um documento diz: dataroom_ask, dataroom_draft_answer, dataroom_compare_files e dataroom_generate_update;
  • POST /api/v1/chat, a mesma resposta de IA pela API REST;
  • o quote de cada fato que GET /api/v1/facts retorna.

Um token sem essa permissão é recusado nessas ferramentas (GRANT_REQUIRED) e nessas rotas REST (PAT_GRANT_REQUIRED), e translate_file_status retorna o status com download_withheld_reason: content_grant_required em vez de um link. GET /api/v1/facts e dataroom_list_facts retornam cada fato sem o seu quote, com value cortado em 20 palavras e value_truncated definido. O token ainda pode listar e pesquisar, e ler o resumo de um documento com get_file_metadata ou dataroom_summarise_file. Tokens criados antes de esta opção existir não podem ler o conteúdo de documentos: crie um novo com Ler conteúdo do documento ativado. Tokens de serviço não são afetados.

Cada token pode obter no máximo 10 links de download por minuto. Acima disso, get_file_download_url é recusado (RATE_LIMITED) e translate_file_status retorna o status com download_withheld_reason: rate_limited; peça novamente após um minuto.

Permitir que um token envie para pessoas fora da sua organização

Criar um link de compartilhamento, adicionar um visualizador de snapshot, convidar um membro da equipe ou um investidor e prorrogar ou restabelecer o acesso de um investidor (dataroom_extend_investor_access, dataroom_reinstate_investor_access) concedem acesso a alguém de fora da sua organização, por isso exigem um token com Enviar para pessoas fora da sua organização ativado (a mesma permissão que envia atualizações para investidores, respostas de Q&A e solicitações de assinatura eletrônica). Você escolhe isso ao criar um token write ou admin em Complementos → Configuração. A lista de tokens mostra Pode enviar para fora em cada um desses tokens.

Seu assistente mostra primeiro quem um novo link admite, a regra de NDA e a expiração, e só o cria quando você confirma. Revogar um link ou um visualizador não exige nenhuma permissão.

A permissão também cobre dar a alguém de fora da sua equipe da transação (proprietários, administradores e membros) acesso, ou mais acesso, a uma sala ou a um documento. "De fora" significa qualquer pessoa que não seja membro ativo da equipe da transação da organização da sala: investidores, convidados, pessoas com um convite pendente e membros de outra organização. Sem a permissão, um token é recusado (GRANT_REQUIRED no MCP) para:

  • uma concessão de leitura ou download a essa pessoa: set_file_permissions, dataroom_set_folder_permissions, dataroom_bulk_set_file_permissions;
  • remover uma negação dessa pessoa, o que restaura seu acesso: revoke_file_permission, dataroom_revoke_folder_permission, dataroom_bulk_revoke_file_permissions;
  • acesso à sala para essa pessoa, em qualquer nível: invite_user_to_dataroom;
  • alterar a função de um membro cuja função atual não é da equipe da transação, o que o promove: dataroom_team_change_member_role;
  • uma alteração de investidor que amplia o acesso: dataroom_set_investor_permissions de visualizador para quem pode baixar, desativar o NDA ou ativar o monitoramento ou as atualizações.

Negações, o encerramento de uma concessão e concessões à sua equipe da transação não exigem a permissão. Conteúdo colocado onde uma pessoa já tem acesso (upload, movimentação, publicação) não é coberto. Anexar um NDA de empresa que a empresa já assinou não exige a permissão.

A mesma permissão se aplica a estas chamadas REST feitas com um token de acesso pessoal:

  • POST /api/share-links (criar um link) e POST /api/snapshots/{id}/viewers são recusadas com 403 PAT_GRANT_REQUIRED sem ela;
  • POST /api/investors/invite (cria um link pessoal e o envia por e-mail) é recusada da mesma forma;
  • PATCH /api/investors/{id}/extend e PATCH /api/investors/{id}/access (restabelecer um investidor ou aprovar uma solicitação de acesso) são recusadas da mesma forma; revogar um investidor (DELETE /api/investors/{id}/access) não exige a permissão;
  • POST /api/team, POST /api/v1/team e POST /api/team/resend (um convite de equipe envia por e-mail um link de entrada) são recusadas da mesma forma;
  • PATCH /api/share-links/{id} é recusada para qualquer edição das configurações de acesso de um link (ativá-lo, seu modo, domínios, expiração ou NDA, quer a edição os amplie ou os restrinja); desativar um link é sempre permitido;
  • GET /api/share-links responde sem o url e o token de cada link, marcados com urlWithheld: true, com um urlWithheldReason explicando o motivo;
  • POST /api/v1/grants é recusada para uma concessão de leitura ou download a alguém de fora da equipe da transação; DELETE /api/v1/grants/{id} é recusada quando a concessão é a negação dessa pessoa; PATCH /api/v1/team/{id} é recusada quando a função atual do membro não é da equipe da transação.

Essas verificações leem o caminho da forma como o servidor o roteia, então uma barra final ou um caractere codificado em porcentagem não as contorna. Um caminho que não pode ser decodificado, ou que contém um segmento ./.. ou uma / codificada dentro de um segmento, não pode ser associado a nenhuma das chamadas que uma permissão cobre. Assim, um token de acesso pessoal que não tenha qualquer permissão por requisição — esta, Ler conteúdo do documento ou Ler análise de engajamento — tem todo caminho desse tipo recusado com 403 PAT_PATH_MALFORMED, seja qual for a chamada.

Tokens criados antes de esta permissão existir não a possuem, então perdem essas chamadas até que você crie um novo token write ou admin com a opção ativada. Um token read não pode ter essa permissão.

Permitir que um token leia a análise de engajamento

Ler análise de engajamento permite que um token leia quem visualizou quais documentos, quando e por quanto tempo: as ferramentas de engajamento e os dados de engajamento na lista de investidores. Ative-a apenas para um assistente que deva ver isso. Qualquer escopo pode tê-la.

A mesma permissão se aplica às leituras de atividade REST: GET /api/v1/activity (o feed de atividades e auditoria da organização), /api/v1/activity/rollups, /api/v1/activity/engagement, /api/v1/activity/engagement/documents e /api/v1/activity/engagement/document/pages. Sem ela, um token de acesso pessoal é recusado com 403 PAT_GRANT_REQUIRED. Tokens de serviço e sessões com login não são afetados.

Tokens criados antes de essas opções existirem não têm nenhuma delas: crie um novo com a opção ativada.

Restringir um token a salas de dados específicas

Por padrão, um token pode acessar todas as salas de dados às quais seu dono tem acesso. Desmarcar Todas as salas de dados e selecionar salas específicas restringe o token a essa lista de permissões: qualquer chamada de ferramenta que faça referência a uma sala de dados fora da lista é rejeitada, e um token com escopo restrito nem sequer vê os nomes das salas de dados que não pode abrir. Use isso para dar a um cliente de IA acesso a uma única transação sem expor o restante do seu portfólio.

Expiração

Todo token expira. Não existe PAT perpétuo: um token que nunca expirava era, ele próprio, a falha de segurança que este comportamento existe para corrigir, porque uma credencial esquecida continua válida para sempre. Definir uma data de expiração faz o token parar de funcionar após essa data — uma requisição com um token expirado é rejeitada exatamente como uma com token revogado, com HTTP 401.

  • Deixe o campo em branco e você terá 90 dias, contados a partir do momento em que o token é emitido. Em branco significa usar o padrão, não nunca expirar.
  • Defina uma data e ela será respeitada exatamente, até um limite de 365 dias a partir da emissão.
  • Peça mais de 365 dias e a solicitação será recusada, não encurtada silenciosamente — a emissão nunca devolve um token com vida mais curta do que você pediu sem avisar. Uma data no passado é recusada da mesma forma.

Portanto, se uma integração deve continuar funcionando, defina a expiração deliberadamente e coloque um lembrete no calendário para substituir o token antes que ele expire — um campo em branco vai interromper silenciosamente essa integração cerca de três meses depois que você a configurou. Não há ação de renovação ou rotação em um token existente e nenhum aviso antes de ele expirar: substituí-lo significa emitir um novo token, atualizar a configuração do seu cliente e revogar o antigo. Por outro lado, uma expiração curta é exatamente o certo para um token que você emite para uma tarefa pontual.

A lista de tokens em Complementos → Configuração mostra a expiração de cada token, para que você possa ver o que está prestes a expirar.

A exibição única

Quando você emite um token, o valor bruto — ele começa com waafir_pat_ — é exibido exatamente uma vez, logo após a criação. O Waafir nunca armazena o token bruto, apenas um hash unidirecional dele, por isso ele não pode ser recuperado nem exibido novamente.

  • Copie-o agora e cole-o diretamente na configuração do seu cliente. O painel de exibição tem um botão de copiar.
  • Se você o perder, não poderá recuperá-lo — revogue esse token e emita um novo.
  • Trate-o como uma senha: ele concede seu escopo a qualquer pessoa que o tenha.

Após a exibição, a lista de tokens só mostra um prefixo curto e não secreto (por exemplo, waafir_pat_ab12…) para que você possa distinguir seus tokens sem que o segredo seja recuperável.

Revogar um token

Na lista de tokens em Complementos → Configuração, use a ação Revogar ao lado de qualquer token. A revogação é imediata — a próxima requisição que usar o token é rejeitada. Revogue um token no momento em que um dispositivo for perdido, um prestador de serviços sair ou você simplesmente não precisar mais do acesso. Tokens revogados continuam visíveis na lista (marcados como revogados), para que o registro do que existiu seja preservado; eles nunca podem ser reativados.

Quando um token termina por conta própria

Um token age por meio da sua associação à organização, então ele termina quando essa associação termina. Você não precisa revogá-lo quando:

  • Você sai da organização ou um administrador remove você. Todos os tokens que você tem nessa organização são revogados nesse momento. Os tokens que você tem em outras organizações continuam funcionando.
  • Um administrador do Waafir exclui sua conta. Seus tokens em todas as organizações são revogados.
  • Um administrador do Waafir exclui a organização. Todos os tokens dela são revogados, incluindo seus tokens de serviço.

Essas revogações são permanentes. Ser convidado de novo, ou ter sua conta ou a organização restauradas, não traz um token de volta: emita um novo.

Um token de serviço pertence à organização, não ao administrador que o criou, então ele continua funcionando quando esse administrador sai. Apenas revogá-lo, ou excluir a organização, o encerra antes do prazo.

O histórico de tokens no log de auditoria

Cada token emitido ou revogado grava uma linha no log de auditoria da organização: quem fez isso, o nome do token, o escopo, as permissões e a expiração, a quantas salas de dados ele está limitado e por que foi revogado (pelo seu dono, porque uma associação terminou ou porque uma conta ou organização foi excluída). O token em si, seu hash e seu prefixo nunca são registrados. As linhas aparecem na trilha de atividades completa, não no resumo do painel.

Se o Waafir não conseguir registrar um novo token no log de auditoria, o token não é emitido e você vê "O token não foi criado porque não conseguimos registrá-lo. Tente novamente."

Próximo passo: configure seu cliente com o token que você acabou de emitir.