Skip to main content
Quatro famílias de credencial, quatro superfícies. Uma credencial de uma nunca abre as rotas de outra — isso é garantido pelo prefixo, antes de qualquer consulta ao banco. Detalhes completos em Credenciais.

​
Sessões de staff

Consiga uma no cadastro, no login, ou na troca de dois fatores:
Contas com dois fatores respondem isto no lugar, e nenhuma sessão é emitida ainda:
Ramifique em two_factor_required, depois troque o desafio em /v1/auth/two-factor dentro de 5 minutos. Veja Dois fatores. Depois envie em toda requisição:
Sessões vivem 30 dias e são revogáveis: sair, trocar a senha e redefinir a senha matam todas elas no servidor. Perder um vínculo não mata — custa aquela organização (403 not_a_member) e deixa a sessão valendo para as outras. Perder o ÚLTIMO também não mata. O login responde 200 com active_organization_id nulo e organizations vazio, e a sessão alcança exatamente quatro rotas: GET /v1/session, GET /v1/organizations, POST /v1/organizations e POST /v1/session/logout. Todo o resto responde 403 not_a_member. Verifique active_organization_code antes de mandar alguém para dentro de uma organização.

​
Chaves de API

Só no servidor. Criadas no painel, mostradas uma vez.
O ambiente da chave é resolvido a partir da linha armazenada em toda requisição. Chame /v1/me uma vez no start-up para confirmar qual você está segurando.

​
Chaves publicáveis

Não é header. Vai no corpo dos endpoints que a aceitam:
O portão não é o CORS — esses caminhos respondem a qualquer origem, deliberadamente. O portão é a lista de origens permitidas da chave. Vazia significa qualquer origem; preenchida significa só correspondências exatas, e um header Origin ausente é recusado.

​
Sessões de contato

Emitidas pelo boot, por um magic link resgatado ou por um código por e-mail. Leem aquele contato e mais nada.
O verified na sessão diz se a identidade por trás dela foi comprovada. Uma sessão não verificada é usável e fica marcada, mas é barrada de qualquer coisa por onde os dados de outra pessoa pudessem vazar.

​
Falhas

​
Credencial ausente, malformada, expirada ou revogada, e nada mais. Ela diz que a credencial acabou, então descartá-la e entrar de novo é a reação certa.
​
A sessão é válida; a organização nomeada em X-Organization-Id não é uma das suas. Mesma resposta para a organização de outra pessoa, para uma que não existe e para um código malformado — distinguir os casos seria um diretório dos nossos tenants. O conserto é trocar de organização, nunca deslogar: a sessão continua boa para as que são suas.
​
Autenticado e membro, mas o seu papel não carrega a permissão. Diferente do 401: logar de novo não vai ajudar.
​
Também a resposta para um recurso em outra organização ou outro ambiente. O 404 nunca revela qual.

​
Levando a família errada

Uma credencial bem formada de outra família recebe isso, em vez de um “inválido” seco:
401
Um caso é erro de configuração, o outro é evento de segurança. Eles não deveriam ler igual nos seus logs.

​
Não revelar se uma conta existe

Vários endpoints respondem igual havendo ou não conta para aquele endereço. Isso é deliberado e vale preservar se você mexer nesses caminhos: Sem a equalização de tempo, só contas reais pagariam as dezenas de milissegundos do bcrypt, e a latência sozinha responderia a pergunta que o código de status se recusa a responder.