Autenticación

El Backoffice usa Google OAuth 2.0 de forma exclusiva — no existen contraseñas. La autenticación es manejada por NextAuth.js 5 en el frontend, que intercambia tokens de Google con el Identity Service para crear una sesión JWT.

Flujo de inicio de sesión

1. El usuario navega al Backoffice y hace clic en Iniciar sesión con Google.
2. El navegador redirige a la pantalla de consentimiento OAuth de Google.
3. El usuario otorga el permiso. Google redirige de vuelta a /api/auth/callback/google.
4. NextAuth intercambia el código de autorización por un token de Google.
5. El frontend llama a POST /v1/auth/signin en el Identity Service con { email, displayName, provider: "google", providerId }.
6. El Identity Service crea o actualiza el registro del usuario y devuelve un JWT firmado.
7. NextAuth almacena el JWT en una cookie de sesión cifrada.

Claims del JWT

Cada llamada a la API del Campaign Service incluye el JWT y un conjunto de cabeceras derivadas de la sesión:

Cabecera	Contenido
Authorization: Bearer {token}	JWT firmado
X-Percus-Forwarded-User-Id	GUID del usuario
X-Percus-Forwarded-User-Name	Nombre de visualización
X-Percus-Forwarded-Active-Org	GUID de la organización activa
X-Percus-Forwarded-Org-Role	Rol en la organización (ej. OrganizationAdmin)
X-Percus-Forwarded-System-Role	Rol de sistema (Owner), si está asignado

El propio JWT contiene estos claims:

{
  "sub": "user-uuid",
  "active_org": "org-uuid",
  "org_role": "OrganizationAdmin",
  "system_role": "Owner",
  "exp": 1234567890
}

system_role solo está presente para usuarios con el rol de Owner a nivel de plataforma.

Cambio de organización

Un usuario puede pertenecer a múltiples organizaciones. El cambio se realiza mediante:

POST /v1/auth/switch-org
{ "organizationId": "uuid" }

El Identity Service devuelve un nuevo JWT con los claims active_org y org_role actualizados. El frontend restablece la sesión con el nuevo token.

Estados del usuario

Estado	Significado
Pending	Invitado pero aún no ha aceptado
Active	Puede iniciar sesión y usar la plataforma
Deactivated	Acceso revocado por un administrador; no puede iniciar sesión
Suspended	Suspendido por la plataforma; no puede iniciar sesión

Un usuario Pending pasa a Active cuando acepta su invitación mediante POST /v1/users/{userId}/accept-invitation.

Flujo de invitación

1. Un OrganizationAdmin llama a POST /v1/users/invite con el email del invitado y el rol deseado.
2. El sistema crea un usuario Pending y (cuando el email está configurado) envía un correo de invitación.
3. El invitado acepta mediante el enlace de invitación → el usuario pasa a Active.
4. Los administradores pueden reenviar invitaciones con POST /v1/users/{userId}/resend-invitation.