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ção | Pergunta | Recusa |
|---|---|---|
| Escopo do token | O escopo do token cobre o que este endpoint faz? | PAT_SCOPE_INSUFFICIENT 403 |
| Função | O chamador tem a função que este endpoint exige? | FORBIDDEN 403 ou PAT_ROLE_CEILING 403 |
| Sala de dados | Para 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,HEADeOPTIONSprecisam deread.- Todos os outros métodos (
POST,PATCH,PUT,DELETE) precisam dewrite.
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çalhoAuthorization, ou um token desconhecido, expirado ou revogado.404para 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, um400que identifica o arquivo, ou um404para 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 responderMFA_SETUP_REQUIREDouMFA_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.