> ## Documentation Index
> Fetch the complete documentation index at: https://docs.assessiq.digital/llms.txt
> Use this file to discover all available pages before exploring further.

# Autenticação

> Como autenticar nas rotas da API do AssessIQ.

<Note>
  O login é feito via **POST** com as credenciais no corpo da requisição (JSON). **Nunca** são enviadas via URL (GET query params).
</Note>

## Fluxo de Autenticação (2 etapas)

O AssessIQ usa um fluxo de duas etapas antes de criar a sessão:

<Steps>
  <Step title="Verificar credenciais + 2FA">
    `POST /api/auth/check-credentials` — valida email/senha e informa se 2FA é necessário.
  </Step>

  <Step title="Criar sessão NextAuth">
    `signIn('credentials', { email, password })` via **NextAuth.js** — cria o cookie JWT de sessão.
  </Step>
</Steps>

***

## POST /api/auth/check-credentials

Valida as credenciais e retorna se o usuário precisa passar por 2FA.

### Request

```http theme={null}
POST /api/auth/check-credentials
Content-Type: application/json

{
  "email": "usuario@exemplo.com",
  "password": "minhasenha"
}
```

### Resposta — sem 2FA

```json theme={null}
{
  "success": true,
  "requires2fa": false
}
```

### Resposta — com 2FA habilitado

```json theme={null}
{
  "success": true,
  "requires2fa": true,
  "methods": ["email", "totp"]
}
```

### Erros

| Status | Descrição                                       |
| ------ | ----------------------------------------------- |
| `400`  | Email ou senha ausentes                         |
| `401`  | Credenciais inválidas                           |
| `429`  | Muitas tentativas (rate limit: 5/10 min por IP) |

<Warning>
  Após 5 tentativas falhas em 10 minutos, o IP fica bloqueado por 10 minutos.
</Warning>

***

## POST /api/auth/callback/credentials

Endpoint interno do NextAuth que cria a sessão. É chamado automaticamente pelo `signIn()` do `next-auth/react` — **não chame diretamente**.

```http theme={null}
POST /api/auth/callback/credentials
Content-Type: application/x-www-form-urlencoded

email=usuario@exemplo.com&password=suasenha&csrfToken=TOKEN&callbackUrl=/pt/home
```

O cookie `next-auth.session-token` (HttpOnly, Secure) é retornado na resposta.

***

## Obtendo o CSRF Token

Necessário para chamar o endpoint de callback diretamente (clientes não-browser).

```http theme={null}
GET /api/auth/csrf
```

```json theme={null}
{
  "csrfToken": "abc123..."
}
```

***

## Verificar Sessão Atual

```http theme={null}
GET /api/auth/session
```

```json theme={null}
{
  "user": {
    "id": "user_id",
    "email": "usuario@exemplo.com",
    "name": "Nome do Usuário",
    "role": "PROFESSOR"
  },
  "expires": "2026-03-24T20:00:00.000Z"
}
```

***

## Logout

```http theme={null}
POST /api/auth/logout
```

***

## OAuth (Google)

```
GET /api/auth/signin/google
```

Redireciona para o fluxo OAuth do Google. Após autenticação, retorna para `/{locale}/home`.

***

## Notas de Segurança

* Senhas armazenadas com **bcrypt** (cost factor 10)
* Senha mínima: **8 caracteres**
* Sessões expiram e são invalidadas via `sessionVersion` no banco
* 2FA disponível por e-mail ou TOTP
* `DEFAULT_DEV_PASSWORD` bloqueado em produção — usuários sem senha devem usar o fluxo "esqueci minha senha"