Autenticación

La API de ZenFlip soporta dos métodos de autenticación: login con email/contraseña (tokens JWT) y Google OAuth. Las claves API para comunicación servidor a servidor están próximamente. Todos los endpoints protegidos requieren un token Bearer válido en la cabecera Authorization.

Login con email y contraseña

Registro

Crea una nueva cuenta y organización:

Después del registro, se envía un email de verificación. La cuenta debe ser verificada antes de que se conceda acceso completo.

Login

Intercambia credenciales por tokens JWT:

Respuesta:

El accessToken caduca después del número de segundos indicado por expiresIn (por defecto: 3600 segundos / 1 hora). El refreshToken tiene una vida útil más larga y se usa para obtener nuevos tokens de acceso sin volver a introducir credenciales.

Usar tokens

Incluye el token de acceso en la cabecera Authorization para todas las solicitudes protegidas:

Usando JavaScript fetch:

Actualización de tokens

Cuando el token de acceso caduca, usa el token de actualización para obtener un nuevo par sin pedir al usuario que inicie sesión de nuevo:

Respuesta:

Tanto el token de acceso como el de actualización se rotan en cada llamada de actualización. Almacena el nuevo token de actualización y descarta el antiguo. Si usas el panel web de ZenFlip, los tokens también se establecen como cookies httpOnly automáticamente.

Ejemplo de actualización en JavaScript

Google OAuth

ZenFlip soporta Google OAuth para inicio de sesión único. Este flujo es basado en navegador y usa redirecciones del lado del servidor.

Flujo

1. Redirige al usuario a https://api.zenflip.io/v1/auth/google.

2. El usuario se autentica con Google y otorga consentimiento.

3. Google redirige a https://api.zenflip.io/v1/auth/google/callback.

4. La API establece cookies de autenticación httpOnly y redirige al usuario a tu URL de callback del frontend (ej., https://app.zenflip.io/auth/google/callback?isNew=0).

El parámetro isNew indica si se creó una nueva cuenta (1) o si el usuario inició sesión en una cuenta existente (0). Tu frontend lee este flag para decidir si mostrar el onboarding.

Ejemplo de integración

Después del callback de OAuth, el navegador del usuario tiene las cookies de autenticación establecidas. Las llamadas posteriores a la API desde el navegador se autenticarán a través de esas cookies.

Claves API (servidor a servidor) --- Próximamente {#api-keys}

Para integraciones de backend, webhooks o pipelines CI/CD, las claves API proporcionarán una ruta de autenticación más simple que no requiere el flujo de login/actualización. Hasta entonces, usa tokens JWT para todo acceso a la API.

Verificación de email

Las nuevas cuentas requieren verificación de email. La API proporciona endpoints para verificar y reenviar el email de verificación:

Restablecimiento de contraseña

Si un usuario olvida su contraseña, inicia un flujo de restablecimiento:

Perfil del usuario actual

Recupera el perfil del usuario autenticado:

Cerrar sesión

Invalida la sesión actual y limpia las cookies:

Límites de tasa

Los endpoints de autenticación tienen sus propios límites de tasa para prevenir abusos: