Autenticação

Visão geral

A autenticação da API é fornecida pelo Better Auth e exposta em https://api.ascendteam.cloud/api/v1/auth. O endpoint é um catch-all (todas as rotas sob /api/v1/auth/*), portanto o Swagger exibirá apenas um item genérico. A listagem completa de endpoints é gerada pelo próprio Better Auth via OpenAPI. No app web, as chamadas autenticadas passam pelo BFF em /api/v1/*.

OpenAPI do Better Auth

A documentação OpenAPI é servida automaticamente em:

https://api.ascendteam.cloud/api/v1/auth/reference

Essa rota é criada pelo plugin openAPI e deve ser usada como referência completa de endpoints.

Admin plugin (rotas de administração)

Habilitamos o plugin admin no Better Auth. Ele adiciona endpoints administrativos para:

criar/gerenciar usuários
banir/desbanir usuários
alterar senha
gerenciar sessões (revogar sessões, etc.)
listas e buscas administrativas

A lista exata de rotas e payloads está na OpenAPI do Better Auth.

Papel (role) e admin

Nosso banco usa role como texto com valores:

user (default)
admin

Você pode tornar o primeiro usuário admin de 2 formas:

Definir ADMIN_USER_IDS no .env (lista separada por vírgula)
Atualizar manualmente o campo role para admin
Usar o endpoint POST /api/v1/admin/bootstrap/promote com o header x-admin-bootstrap-token definido em ADMIN_BOOTSTRAP_TOKEN

O plugin admin usa esses valores para autorização.

Reset de senha (email)

Fluxo padrão:

POST /api/v1/auth/request-password-reset
Email enviado com link para o usuário (Resend)
Link redireciona para /forgot-password/reset?token=...
POST /api/v1/auth/reset-password com token e newPassword

Variáveis de ambiente (Resend)

RESEND_API_KEY (necessária para entrega de reset em qualquer ambiente)
RESEND_FROM_EMAIL (necessária para entrega de reset em qualquer ambiente; ex.: Ascend <no-reply@ascendteam.cloud>)
BETTER_AUTH_LOG_RESET_URL (flag legada; não cria canal local seguro)

BETTER_AUTH_LOG_RESET_URL não habilita entrega local no wiring atual. Se o Resend estiver ausente ou incompleto, o fluxo falha fechado com erro genérico e não registra, persiste ou expõe dados de redefinição. Configure RESEND_API_KEY e RESEND_FROM_EMAIL para habilitar o envio real pelo Resend.

Como autenticar no front-end

No front-end, o fluxo recomendado é usar o client do Better Auth (em vez de chamar as rotas diretamente), com métodos como signUp/signIn/getSession. A OpenAPI é referência para o backend e para chamadas diretas, quando necessário.