Status: Approved · v2 · SPEC-API-AUTH-001

depends_on: SPEC-DOMAIN-AUTH-001, SPEC-DOMAIN-TERRITORY-001

used_by: IS-MVP-02.1, IS-MVP-02.2, IS-MVP-02.3, IS-MVP-02.4

API de autenticação, onboarding e AuthIntent

Cria sessões, conclui onboarding e preserva ações protegidas iniciadas por visitantes.

Princípios e padrões

• Base path /api/v1; JSON UTF-8; chaves em camelCase.
• Toda resposta usa ApiResponse<T> com ok, data|error e meta contendo requestId e timestamp.
• IDs são strings opacas; datas são ISO-8601 UTC; dinheiro é inteiro em centavos com moeda BRL.
• Listas usam page e pageSize no MVP; default 20, máximo 100; metadados ficam em meta.pagination.
• Endpoints públicos usam DTOs públicos específicos; entidades internas, memberships, saldos e dados privados nunca vazam.
• Erros de domínio são estáveis e acionáveis; stack traces e detalhes internos não são retornados.
• Alterações sensíveis usam Idempotency-Key, confirmação recente quando necessário e audit log.
• Uploads usam fluxo presigned; o backend valida propósito, MIME, tamanho e ownership antes de confirmar o asset.

Endpoints

Método	Rota	Acesso	Request	Response	Regras principais
POST	/auth/intents	Público	CreateAuthIntentRequest	AuthIntentResponse	Cria intenção curta com returnUrl allowlisted.
POST	/auth/register	Público	RegisterRequest	AuthSessionResponse	Cria supporter pending_onboarding e vincula intent opcional.
POST	/auth/login	Público	LoginRequest	AuthSessionResponse	Rate limited; não revela detalhes indevidos.
POST	/auth/refresh	Refresh session	RefreshRequest	AuthTokensResponse	Rotaciona refresh token.
POST	/auth/logout	Autenticado	LogoutRequest	OperationResponse	Revoga sessão atual ou selecionada.
GET	/auth/me	Autenticado	—	AuthMeResponse	Conta, papéis, summaries de jogador e gestão.
POST	/auth/onboarding/complete	Autenticado	CompleteOnboardingRequest	AuthMeResponse	Nome, apelido, distrito, cheers/follows opcionais.
POST	/auth/intents/:intentId/execute	Autenticado	ExecuteAuthIntentRequest	ExecuteAuthIntentResponse	Executa ação após revalidar estado/permission.
POST	/auth/forgot-password	Público	ForgotPasswordRequest	OperationResponse	Resposta neutra.
POST	/auth/reset-password	Público	ResetPasswordRequest	OperationResponse	Token único/expirável.
POST	/players/activate	Autenticado	ActivatePlayerRequest	PlayerMeResponse	Adiciona role player e perfil incompleto.

Autenticação e autorização

• Register/login públicos com rate limiting e anti-enumeration.
• Onboarding, me, logout, player activate exigem sessão.
• AuthIntent não contorna permissão nem estado; apenas preserva contexto.
• Credenciais e tokens nunca são retornados em logs.

Erros de domínio

Código	HTTP	Quando ocorre	Ação esperada no cliente
INVALID_CREDENTIALS	401	Credenciais inválidas	Mensagem neutra.
ACCOUNT_SUSPENDED	403	Conta suspensa	Mostrar suporte.
ONBOARDING_REQUIRED	409	Ação exige onboarding	Continuar onboarding.
AUTH_INTENT_EXPIRED	410	Intent expirou	Retomar ação original.
AUTH_INTENT_INVALID	422	Target/returnUrl inválido	Cancelar fluxo.
EMAIL_OR_PHONE_IN_USE	409	Identificador já cadastrado	Orientar login/recuperação.

Idempotência e concorrência

• Register e execute intent aceitam chave quando a ação alvo é sensível.
• Refresh é rotacionado e replay invalida a família quando configurado.

Auditoria e efeitos colaterais

• Login/logout e alterações de senha geram eventos de segurança sem registrar segredo.
• Conclusão de onboarding pode criar cheer/follow e notificação de boas-vindas.

Exemplos

authIntent

{
  "type": "cheer_team",
  "target": {
    "entityType": "team",
    "entityId": "team_001"
  },
  "returnUrl": "/teams/unidos-do-6"
}

me

{
  "user": {
    "id": "user_001",
    "displayName": "Luan",
    "roles": [
      "supporter",
      "player"
    ],
    "districtId": "district_001"
  },
  "playerSummary": {
    "status": "active",
    "profileCompleteness": 72
  },
  "managementSummary": {
    "entityCount": 2
  }
}

Mocks

• Cenários visitor, pending_onboarding, supporter, player, manager, owner e suspended.
• Intent deve sobreviver a register/login e falhar corretamente se target mudou.

Testes obrigatórios

• Register cria supporter.
• Anti-enumeration em forgot password.
• Intent cheer/follow/report/support/accept invite.
• Refresh rotation e logout.
• Onboarding idempotente.

Critérios de aceite

• Ação original é retomada sem duplicação.
• Todo usuário nasce supporter.
• Distrito é obrigatório ao concluir onboarding.
• SSO não entra no MVP.

Machine summary

spec: SPEC-API-AUTH-001
api_group: API de autenticação, onboarding e AuthIntent
base_path: /api/v1
response_envelope: ApiResponse<T>
ids: string
dates: ISO-8601
money: integer_cents