ADR-701: API & Authentication

Status: Accepted

Contexto

middag-account precisa de REST API para: portal NextJS (frontend headless), apps mobile futuras, integrações de terceiros, e satélites. API do tema legado (v2/v3) não tem envelope padronizado, payload JWT inconsistente (data.user_id aninhado vs sub top-level), sem rate limiting em auth, sem validação de senha. Desenvolvedores integradores precisam de docs completos, contrato estável e tipos TypeScript.

Decisão

REST API v1

Namespace: middag-account/v1. Endpoints registrados via WordPress REST API com permission_callback em TODA rota. Catálogo completo em REF-701-01.

Envelope de Resposta Padronizado

Todos os endpoints retornam:

{
  "success": true,
  "data": { },
  "meta": { "page": 1, "per_page": 20, "total": 100, "pages": 5 },
  "message": null,
  "errors": null
}

Detalhes em REF-701-01.

7 Error Codes

Code	HTTP	Quando
VALIDATION_ERROR	422	Input inválido
AUTHENTICATION_ERROR	401	Sem token ou token inválido
AUTHORIZATION_ERROR	403	Sem permissão para recurso
NOT_FOUND	404	Recurso não existe
CONFLICT	409	Estado conflitante
RATE_LIMIT	429	Limite de requisições excedido
INTERNAL_ERROR	500	Erro interno do servidor

JWT RS256 (Access + Refresh)

• Access token: TTL 24h, RS256 (private key fora do webroot)
• Refresh token: TTL 7d
• Payload: sub, org, roles, scopes no nível superior (não aninhado)
• Nunca HS256 — RS256 permite validação com public key

Detalhes em REF-701-02.

Headers Multi-Tenant e Dual-Entity

Header	Obrigatório	Função
Authorization	Sim	Bearer {jwt_token}
X-Middag-Organization	Sim *	ID da organization (isolamento multi-tenant)
X-Middag-Company	Não	middag_br / middag_global (roteamento)

* Obrigatório em endpoints que operam sobre dados de organization.

Rate Limiting em /auth

5 tentativas por minuto por IP em endpoints /auth/*. Retorna 429 RATE_LIMIT. Previne brute force em login/registro.

Contrato de Estabilidade

Camada	Garantia
REST API v1	Sem breaking changes dentro da v1. Novos endpoints aditivos. Campos nunca removidos. Depreciação com 6 meses de aviso.
WordPress Hooks	Hooks existentes nunca removidos. Novos parâmetros ao final.
Interfaces PHP	Estável dentro da MAJOR. Novos métodos requerem bump MAJOR.

Consequências

Positivas:

• Envelope padronizado elimina inconsistências entre endpoints
• JWT RS256 com payload top-level alinha com padrões modernos
• Rate limiting previne brute force (bloqueador #5 resolvido)
• Contrato de estabilidade dá confiança para desenvolvedores

Negativas:

• RS256 requer gestão de keypair (private key fora do webroot)
• Rate limiting por IP pode afetar clientes atrás de NAT
• Contrato "sem breaking changes" limita refatoração futura

Referências

• REF-701-01 — API Response Contract
• REF-701-02 — Authentication Flow
• ADR-201 — Identity (X-Middag-Organization para multi-tenant)
• ADR-301 — Commerce (X-Middag-Company para dual-entity)
• ADR-103 — Plugin Ecosystem (contrato de estabilidade)
• ADR-103 §Contrato de Estabilidade — API contracts, versioning
• ../reference/personas.md §6 — Developer persona, API contract