Autenticacion
Aprende a autenticarte con la API de ZenFlip usando tokens JWT, tokens de actualizacion y Google OAuth. Las claves API para comunicacion servidor a servidor estaran disponibles pronto.
- Inicio de Sesion con Email y Contrasena
- Registro
- Inicio de Sesion
- Uso de Tokens
- Actualizacion de Token
- Ejemplo de Actualizacion en JavaScript
- Google OAuth
- Flujo
- Ejemplo de Integracion
- Claves API (Servidor a Servidor) — Proximamente {#api-keys}
- Verificacion de Email
- Restablecimiento de Contrasena
- Perfil del Usuario Actual
- Cerrar Sesion
- Limites de Tasa
Autenticacion
La API de ZenFlip admite dos metodos de autenticacion: inicio de sesion con email/contrasena (tokens JWT) y Google OAuth. Las claves API para comunicacion servidor a servidor estan disponibles proximamente. Todos los endpoints protegidos requieren un token Bearer valido en el encabezado Authorization.
Inicio de Sesion con Email y Contrasena
Registro
Crea una nueva cuenta y organizacion:
`bash curl -X POST https://api.zenflip.io/v1/auth/signup \ -H "Content-Type: application/json" \ -d '{ "email": "developer@example.com", "password": "SecureP@ssw0rd!", "name": "Alex Chen", "organizationName": "Acme Publishing" }' `
Despues del registro, se envia un email de verificacion. La cuenta debe ser verificada antes de otorgar acceso completo.
Inicio de Sesion
Intercambia credenciales por tokens JWT:
`bash curl -X POST https://api.zenflip.io/v1/auth/login \ -H "Content-Type: application/json" \ -d '{ "email": "developer@example.com", "password": "SecureP@ssw0rd!" }' `
Respuesta:
`json { "accessToken": "eyJhbGciOiJIUzI1NiIs...", "refreshToken": "eyJhbGciOiJIUzI1NiIs...", "expiresIn": 3600, "user": { "id": "550e8400-e29b-41d4-a716-446655440000", "email": "developer@example.com", "name": "Alex Chen", "role": "owner", "emailVerified": true }, "organization": { "id": "660e8400-e29b-41d4-a716-446655440000", "name": "Acme Publishing", "plan": "creator" } } `
El accessToken expira despues del numero de segundos indicado por expiresIn (por defecto: 3600 segundos / 1 hora). El refreshToken tiene una vida util mas larga y se usa para obtener nuevos tokens de acceso sin volver a ingresar las credenciales.
Uso de Tokens
Incluye el token de acceso en el encabezado Authorization para todas las solicitudes protegidas:
`bash curl https://api.zenflip.io/v1/publications \ -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." `
Usando JavaScript fetch:
`javascript const response = await fetch("https://api.zenflip.io/v1/publications", { headers: { "Authorization": Bearer ${accessToken}, "Content-Type": "application/json" } }); const { data, meta } = await response.json(); `
Actualizacion de Token
Cuando el token de acceso expira, usa el token de actualizacion para obtener un nuevo par sin solicitar al usuario que inicie sesion nuevamente:
`bash curl -X POST https://api.zenflip.io/v1/auth/refresh \ -H "Content-Type: application/json" \ -d '{ "refreshToken": "eyJhbGciOiJIUzI1NiIs..." }' `
Respuesta:
`json { "accessToken": "eyJhbGciOiJIUzI1NiIs...", "refreshToken": "eyJhbGciOiJIUzI1NiIs...", "expiresIn": 3600 } `
Tanto el token de acceso como el token de actualizacion se rotan en cada llamada de actualizacion. Almacena el nuevo token de actualizacion y descarta el anterior. Si usas el panel web de ZenFlip, los tokens tambien se configuran automaticamente como cookies httpOnly.
Ejemplo de Actualizacion en JavaScript
`javascript async function refreshAccessToken(currentRefreshToken) { const response = await fetch("https://api.zenflip.io/v1/auth/refresh", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ refreshToken: currentRefreshToken }) });
if (!response.ok) { throw new Error("Token refresh failed, user must re-authenticate"); }
const tokens = await response.json(); // Store tokens.accessToken and tokens.refreshToken securely return tokens; } `
Google OAuth
ZenFlip admite Google OAuth para inicio de sesion unico. Este flujo se realiza en el navegador y utiliza redirecciones del lado del servidor.
Flujo
Redirige al usuario a
https://api.zenflip.io/v1/auth/google.El usuario se autentica con Google y otorga consentimiento.
Google redirige a
https://api.zenflip.io/v1/auth/google/callback.La API configura cookies de autenticacion
httpOnlyy redirige al usuario a la URL de callback de tu frontend (ej.,https://app.zenflip.io/auth/google/callback?isNew=0).
El parametro isNew indica si se creo una cuenta nueva (1) o si el usuario inicio sesion en una cuenta existente (0). Tu frontend lee esta marca para decidir si mostrar la incorporacion.
Ejemplo de Integracion
`html <a href="https://api.zenflip.io/v1/auth/google" class="btn-google"> Iniciar sesion con Google </a> `
Despues del callback de OAuth, el navegador del usuario tiene las cookies de autenticacion configuradas. Las llamadas posteriores a la API desde el navegador se autenticaran mediante esas cookies.
Claves API (Servidor a Servidor) — Proximamente {#api-keys}
Proximamente — disponible en el segundo trimestre de 2026. La autenticacion con claves API para integraciones servidor a servidor esta en desarrollo activo. Esta seccion se actualizara cuando la funcionalidad se lance.
Para integraciones de backend, webhooks o pipelines de CI/CD, las claves API proporcionaran una ruta de autenticacion mas sencilla que no requiere el flujo de inicio de sesion/actualizacion. Hasta entonces, usa tokens JWT para todo el acceso a la API.
Verificacion de Email
Las cuentas nuevas requieren verificacion de email. La API proporciona endpoints para verificar y reenviar el email de verificacion:
`bash
Verificar con un token del enlace del email
curl -X POST https://api.zenflip.io/v1/auth/verify-email \ -H "Content-Type: application/json" \ -d '{ "token": "verification-token-from-email" }'
Reenviar el email de verificacion
curl -X POST https://api.zenflip.io/v1/auth/resend-verification \ -H "Content-Type: application/json" \ -d '{ "email": "developer@example.com" }' `
Restablecimiento de Contrasena
Si un usuario olvida su contrasena, inicia un flujo de restablecimiento:
`bash
Solicitar un email de restablecimiento de contrasena
curl -X POST https://api.zenflip.io/v1/auth/forgot-password \ -H "Content-Type: application/json" \ -d '{ "email": "developer@example.com" }'
Restablecer la contrasena con el token del email
curl -X POST https://api.zenflip.io/v1/auth/reset-password \ -H "Content-Type: application/json" \ -d '{ "token": "reset-token-from-email", "password": "NewSecureP@ssw0rd!" }' `
Perfil del Usuario Actual
Obtiene el perfil del usuario autenticado:
`bash curl https://api.zenflip.io/v1/auth/me \ -H "Authorization: Bearer YOUR_TOKEN" `
Cerrar Sesion
Invalida la sesion actual y elimina las cookies:
`bash curl -X POST https://api.zenflip.io/v1/auth/logout \ -H "Authorization: Bearer YOUR_TOKEN" `
Limites de Tasa
Los endpoints de autenticacion tienen sus propios limites de tasa para prevenir abusos:
Endpoint | Limite |
|---|---|
| 5 por minuto |
| 10 por minuto |
| 20 por minuto |
| 3 por minuto |
| 5 por minuto |
| 3 por minuto |