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

Autenticação

Toda solicitação /v1 é autenticada. A partir dos seus próprios sistemas, autentique-se com um token de acesso pessoal (PAT) enviado como token bearer:

Authorization: Bearer waafir_pat_…

Emita, restrinja e revogue tokens em Complementos → Configuração. O guia de tokens de acesso pessoal aborda a emissão, a expiração (90 dias por padrão, no máximo 365), a exibição única e a revogação. Essas regras são as mesmas para a API da plataforma. Esta página aborda o que um token pode fazer depois que você o tem.

Um token de acesso pessoal atua como a pessoa que o emitiu, dentro da organização dessa pessoa. Não há parâmetro de organização em nenhuma URL ou corpo, porque o token já a define.

As três verificações do token

Uma solicitação autenticada por token precisa passar por estas três verificações, entre outras. A política de segurança da organização e as verificações próprias do endpoint também podem recusá-la (veja abaixo). Duas das três têm um código próprio. Uma recusa por função pode responder FORBIDDEN, que outras recusas compartilham, então leia o código junto com os requisitos do endpoint.

VerificaçãoPerguntaRecusa
Escopo do tokenO escopo do token cobre o que este endpoint faz?PAT_SCOPE_INSUFFICIENT 403
FunçãoO chamador tem a função que este endpoint exige?FORBIDDEN 403 ou PAT_ROLE_CEILING 403
Sala de dadosPara um token restrito a salas de dados, esta sala está na lista dele?PAT_DATAROOM_SCOPE 403

Escopos de token

Um token tem um único escopo: read, write ou admin, em ordem crescente de autoridade. Um escopo superior inclui tudo o que está abaixo dele.

O escopo de que um endpoint precisa segue, por padrão, o método HTTP:

  • GET, HEAD e OPTIONS precisam de read.
  • Todos os outros métodos (POST, PATCH, PUT, DELETE) precisam de write.

Alguns endpoints declaram um escopo diferente. O caso mais comum é um POST que apenas executa uma consulta e, portanto, precisa só de read. A referência de endpoints mostra o escopo que cada endpoint realmente exige; confira ali em vez de deduzi-lo pelo método.

Função exigida e teto de função

O escopo diz o que o token pode fazer. A função exigida do endpoint diz quem a pessoa precisa ser. Muitos endpoints /v1 exigem a equipe da transação (um proprietário, administrador ou membro da organização). Alterações na equipe e nas concessões de acesso, entre outras, exigem um proprietário ou administrador. Investidores e outros convidados não têm função na equipe da transação, então os endpoints da equipe da transação os recusam. Outros endpoints não declaram restrição de função na camada de autenticação e verificam o acesso dentro do próprio endpoint. Por exemplo, as rotas de monitoramento de portfólio verificam o complemento de monitoramento e o acesso de monitoramento do chamador. A referência de endpoints mostra a restrição de função de cada endpoint. Onde nenhuma for declarada, saiba que o próprio endpoint ainda pode recusar.

Um token também registra a função de quem o emitiu no momento da emissão, como um teto. A função que o Waafir aplica é a menor entre a função atual do emissor e esse teto. Um membro promovido depois a administrador continua atuando como membro por meio de um token emitido antes; emita um novo token para usar a nova função. Uma pessoa cuja função é reduzida perde a autoridade imediatamente, seja qual for a função registrada no token. Qualquer uma dessas insuficiências é recusada com 403, como FORBIDDEN ou PAT_ROLE_CEILING.

Tokens restritos a salas de dados

Um token emitido com salas de dados específicas selecionadas, em vez de Todas as salas de dados, alcança apenas essas salas. Uma solicitação que mencione qualquer outra sala de dados é recusada com PAT_DATAROOM_SCOPE. Alguns endpoints de toda a organização recusam um token restrito de imediato, com o mesmo código, porque a resposta deles abrange salas de dados que o token não pode ver. Use um token sem restrição para esses casos. GET /api/v1/session aceita os dois tipos.

Outras recusas que você pode encontrar

  • 401 UNAUTHORIZED: sem cabeçalho Authorization, ou um token desconhecido, expirado ou revogado.
  • 404 para um recurso de outra organização. Um id que pertence a outra organização é tratado como não encontrado, de modo que sua existência não é confirmada.
  • Sem exceção de proprietário/administrador em arquivos restritos. No app, um proprietário ou administrador da organização vê todos os arquivos restritos. Um token não: ele só alcança um arquivo restrito se o dono do token o criou ou tem uma concessão sobre ele. Uma solicitação que mencione um arquivo que ele não pode ler recebe a mesma resposta dada a um arquivo inexistente (para /api/v1/grants, um 400 que identifica o arquivo, ou um 404 para a concessão), com uma mensagem dizendo que ele está "not found, or not readable by this credential", de modo que a resposta nunca confirma que o arquivo existe.
  • Política de segurança da organização. Se sua organização tem uma lista de IPs permitidos, uma solicitação vinda de fora dela responde IP_BLOCKED. A exigência de autenticação de dois fatores pode responder MFA_SETUP_REQUIRED ou MFA_CHALLENGE_REQUIRED.
  • 429 RATE_LIMITED. Alguns endpoints declaram um limite por minuto para cada identidade, indicado no endpoint. Os demais usam o padrão da plataforma. Aguarde e tente novamente.

A página de códigos de erro lista os códigos conhecidos com seus significados.