Autenticação

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.

Família	Header	Abre
`uk_st_…`	`Authorization: Bearer`	O plano de staff: conta, organizações, membros, papéis, chaves, leituras de contato no painel
`uk_sk_…`	`Authorization: Bearer`	`/v1/me`, `/v1/contacts`
`uk_pk_…`	corpo da requisição, ou o caminho das leituras endereçadas por ela	`/v1/boot`, `/v1/contact-auth/*`, `/v1/waitlist`, `/v1/jwks/{publishableKey}`, `/v1/config/{publishableKey}`
`uk_ct_…`	`Authorization: Bearer`	`/v1/contact/me`, `/v1/contact/logout`, `/v1/contact/token`, `/v1/contact/sessions`, `/v1/contact/two-factor/*`

Detalhes completos em Credenciais.

Sessões de staff

Consiga uma no cadastro, no login, ou na troca de dois fatores:

curl -s $API/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{ "email": "ada@example.com", "password": "Analytical1" }'

{
  "token": "uk_st_9f3c…",
  "expires_at": "2026-08-28T12:00:00Z",
  "user": { "...": "..." },
  "organizations": [{ "...": "..." }],
  "active_organization_id": "…",
  "active_organization_code": "org_4b1e…"
}

Contas com dois fatores respondem isto no lugar, e nenhuma sessão é emitida ainda:

{ "two_factor_required": true, "challenge_token": "uk_2fa_…" }

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:

curl -s $API/v1/session \
  -H "Authorization: Bearer uk_st_9f3c…" \
  -H "X-Organization-Id: org_4b1e…"

Sessões vivem 30 dias e são revogáveis: sair, trocar a senha, redefinir a senha e perder o vínculo matam todas elas no servidor.

Chaves de API

Só no servidor. Criadas no painel, mostradas uma vez.

curl -s $API/v1/me -H "Authorization: Bearer uk_sk_live_a91c…"

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:

curl -s $API/v1/boot \
  -H 'Origin: https://app.example.com' \
  -H 'Content-Type: application/json' \
  -d '{ "publishable_key": "uk_pk_live_3d8e…", "anonymous_id": "anon_2f9c1b" }'

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, por login hosted, ou por verificação de e-mail. Leem aquele contato e mais nada.

curl -s $API/v1/contact/me -H "Authorization: Bearer uk_ct_…"

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 também “você não é membro daquela organização”, porque o JOIN do vínculo não casa com nada e distinguir os dois casos vazaria que a organização existe.

Autenticado, 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

{
  "error": {
    "code": "unauthorized",
    "message": "this endpoint expects a staff session token, not an organization API key"
  }
}

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:

Endpoint	Comportamento
`POST /v1/auth/login`	Um `401` para e-mail desconhecido, conta sem senha e senha errada — com uma comparação bcrypt descartável para o tempo bater também
`POST /v1/auth/forgot-password`	`202` sempre
`POST /v1/contact-auth/signup`	`202` sempre — três coisas diferentes acontecem por trás
`POST /v1/contact-auth/login`	Um `401`, mesma equalização de tempo
`POST /v1/contact-auth/forgot-password`	`202` sempre
`POST /v1/contact-auth/resend-verification`	`202` sempre
`POST /v1/contact-auth/magic-link`	`202` sempre
`POST /v1/contact-auth/magic-link/redeem`	Um `401` para usado, expirado e nunca existiu
`POST /v1/contact-auth/email-code`	`202` sempre — o desafio é gerado antes de qualquer consulta, então um endereço sem conta também recebe um
`POST /v1/contact-auth/email-code/verify`	Um `401` para errado, expirado, já gasto, e para um desafio que nunca teve código atrás

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.

Visão geral

Endpoints

Sessões de staff

Chaves de API

Chaves publicáveis

Sessões de contato

Falhas

Levando a família errada

Não revelar se uma conta existe

​Sessões de staff

​Chaves de API

​Chaves publicáveis

​Sessões de contato

​Falhas

​Levando a família errada

​Não revelar se uma conta existe

Sessões de staff

Chaves de API

Chaves publicáveis

Sessões de contato

Falhas

Levando a família errada

Não revelar se uma conta existe