API ReferenceAuth
POST /auth/set-password
Definir senha inicial (conta criada via OAuth)
POST
/auth/set-passwordAuth: accessTokenPara usuários cuja conta foi criada via Google OAuth e ainda não tem password_hash definido. Permite ao usuário criar uma senha local pra que possa logar com e-mail/senha (ou desvincular o Google sem perder acesso).
Falha se a conta já tem senha — esse é o caminho pra "primeira senha apenas". Pra trocas subsequentes use PUT /auth/change-password.
Quando chamar
- Tela "Configurações → Segurança", quando o usuário (que entrou via Google) decide criar senha local
- Necessário antes de chamar
DELETE /auth/google/link(desvincular Google) se o user só tem Google como método de login — caso contrário a desvinculação falha comPASSWORD_REQUIRED_BEFORE_UNLINK
Request
| Campo | Tipo | Requerido | Descrição |
|---|---|---|---|
| newPassword | string | sim |
Validação: newPassword 8–100 caracteres.
Header obrigatório: Authorization: Bearer <accessToken>.
Response
204
object404
| Campo | Tipo | Requerido | Descrição |
|---|---|---|---|
| error | string | sim | Mensagem ou código tipado do erro. Códigos canônicos: EMAIL_ALREADY_EXISTS, INVALID_CREDENTIALS, INVALID_RESET_TOKEN, PASSWORD_ALREADY_SET, USER_NOT_FOUND. |
409
| Campo | Tipo | Requerido | Descrição |
|---|---|---|---|
| error | string | sim | Mensagem ou código tipado do erro. Códigos canônicos: EMAIL_ALREADY_EXISTS, INVALID_CREDENTIALS, INVALID_RESET_TOKEN, PASSWORD_ALREADY_SET, USER_NOT_FOUND. |
204 No Content. Frontend mostra "Senha definida — você pode usar e-mail/senha pra entrar agora".
Erros
| Status | Códigos possíveis (extraídos do schema) |
|---|---|
| 404 | Mensagem ou código tipado do erro |
| 409 | Mensagem ou código tipado do erro |
Como resolver cada caso:
| Status | Código | Causa | Como resolver |
|---|---|---|---|
| 401 | (sem corpo) | JWT ausente/inválido | Refresh ou login |
| 409 | PASSWORD_ALREADY_SET | Já existe users.password_hash | Use change-password em vez disso |
| 404 | USER_NOT_FOUND | User do JWT não existe mais (conta deletada) | Logout + re-login |
| 400 | Validação Zod | newPassword fora dos 8–100 | Mostrar erro no campo |
Exemplos
curl -X POST 'http://localhost:3003/auth/set-password' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer SEU_ACCESS_TOKEN' \
-d '{}'await fetch('http://localhost:3003/auth/set-password', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Authorization: 'Bearer ' + accessToken,
},
body: JSON.stringify({}),
})Resposta de sucesso
HTTP/1.1 204 No ContentSide effects
- DB:
UPDATE users SET password_hash = bcrypt(newPassword) WHERE id = userId - NÃO mexe em
refresh_tokens - Sem e-mail ou notificação
Relacionados
- Endpoint:
PUT /auth/change-password— pra trocar senha já existente - Endpoint:
DELETE /auth/google/link— desvincular Google após ter senha - Endpoint:
GET /auth/google/callback— onde a conta foi criada inicialmente sem senha - Tabela:
users— campopassword_hash