Autenticación por cookies

Este es el método por defecto y el más simple de usar. Es ideal para aplicaciones web y cuando trabajas desde un navegador o herramientas como Postman.

🚧

Tu aplicación debe correr en un dominio autorizado por la API y tu cliente HTTP debe soportar cookies. Si no cumples estos requisitos, usa el método de Bearer Token.

Paso 1: Iniciar sesión con Cookies

Para iniciar sesión usando el método de cookies, debes enviar una petición POST al endpoint /v1/sessions usando HTTP Basic Authentication.

Cómo codificar tus credenciales

¿Qué es Base64?

Base64 es una forma de codificar información para enviarla de manera segura. Es como "traducir" tus credenciales a un formato que la API puede entender.

¿Cómo funciona?

Debes enviar tus credenciales codificadas en Base64 en un header especial llamado Authorization:

Authorization: Basic <token_base64>

Donde <token_base64> es la codificación Base64 de email:credencial, siendo credencial tu contraseña o tu api_token.

Proceso:

1. Combina tu email y credencial con dos puntos (:): email:credencial. Ejemplo: [email protected]:DummyPass1@
2. Codifica esa cadena en Base64 usando un comando o herramienta.
3. Envía el valor codificado en el header Authorization con el prefijo Basic.

Opciones de credenciales

Puedes usar dos tipos de credenciales para iniciar sesión. Ambas funcionan igual, solo cambia qué credencial usas:

Opción A: Email y contraseña

# Generar el token Base64
echo -n "[email protected]:DummyPass1@" | base64
# Resultado: dXN1YXJpb0BlamVtcGxvLmNvbTpNaUNvbnRyYXNlw7FhMTIzQA==

Opción B: Email y API Token

# Generar el token Base64
echo -n "[email protected]:9d459233974f1500aa79d94f550c2694" | base64
# Resultado: dXN1YXJpb0BlamVtcGxvLmNvbTo5ZDQ1OTIzMzk3NGYxNTAwYWE3OWQ5NGY1NTBjMjY5NA==

Ejemplo de petición de login con Curl

curl --location --request POST 'https://nominapp-api-stage.herokuapp.com/v1/sessions' \
--header 'Authorization: Basic dXN1YXJpb0BlamVtcGxvLmNvbTpNaUNvbnRyYXNlw7FhMTIzQA==' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json'

Paso 2: Qué recibes después del login

Cuando inicias sesión exitosamente, la API hace dos cosas importantes:

1. Establece cookies automáticamente: La API crea dos cookies especiales y las envía en los headers de respuesta. Tu cliente HTTP (navegador, Postman, etc.) las guarda automáticamente.
2. Devuelve información del usuario: La respuesta JSON incluye tus datos de usuario.

Cookies que se crean

Configuración de seguridad

Las cookies tienen estas características de seguridad:

• HttpOnly: No accesibles desde JavaScript (mayor seguridad).
• Secure: Solo se envían por HTTPS.
• SameSite=None: Permiten funcionar desde otros dominios (útil para aplicaciones React, Angular, etc.).
• Automáticas: Se envían automáticamente en cada petición sin que necesites hacer nada.

Respuesta del login

La respuesta JSON incluye información del usuario, pero importante: no incluye tokens en el body de la respuesta. Los tokens de sesión están en las cookies que se crean automáticamente. Esto es normal y esperado:

{
  "data": {
    "user": {
      "id": "3a4b8cc7-fb8c-4eac-94fb-c0b6b39bbcf1",
      "email": "[email protected]",
      ...
    },
    "created_at": 1764301434981,
    "is_new_user": false
  }
}

Paso 3: Cómo hacer peticiones siguientes

Una vez que has iniciado sesión, las cookies se manejan automáticamente. Simplemente, haz tus peticiones normalmente y las cookies se enviarán automáticamente.

En navegadores y Postman:

Las cookies se envían automáticamente en cada petición. Tu navegador o Postman las maneja por ti, no necesitas configurar nada.

Ejemplo de petición después del login:

GET /v1/economic_sectors

Content-Type: application/json
Accept: application/json

Renovación de la sesión

• El token expira en 4 horas, pero la API lo renueva automáticamente usando el refresh_token.
• El refresh_token expira en 12 horas. Después de ese tiempo, debes hacer login de nuevo.
• La sesión máxima es de 12 horas.

Ventajas de usar Cookies

• ✅ Simplicidad: No necesitas manejar tokens manualmente.
• ✅ Seguridad: Las cookies HttpOnly no son accesibles desde JavaScript.
• ✅ Automático: Tu cliente HTTP (navegador, Postman, cURL) las maneja automáticamente.
• ✅ Renovación automática: El sistema puede renovar tu sesión automáticamente usando el refresh_token.

Limitaciones de las Cookies

⚠️ Dependiente del cliente: Requiere que tu herramienta o aplicación pueda manejar cookies. Si tu cliente HTTP no soporta cookies, este método no funcionará.

⚠️ Dominio autorizado: Tu aplicación debe correr en un dominio autorizado en la configuración CORS de la API.

Errores comunes

Error 401: No autorizado

Causa: Tu sesión ha expirado o las cookies no se están enviando correctamente.

Solución:

• El token expira en 4 horas (o 12 horas con refresh). Inicia sesión nuevamente.
• Verifica que las cookies no hayan sido eliminadas o modificadas.

Las cookies no se envían automáticamente

¿Qué significa este problema?

Las cookies que deberían enviarse automáticamente con cada petición no se están enviando, lo que causa errores de autenticación.

Causas y soluciones:

1. Tu herramienta no soporta cookies

Causa: Algunas herramientas o librerías no pueden manejar cookies automáticamente.

Solución: Usa Bearer Token en su lugar, que no depende de cookies.

2. Tu dominio no está autorizado

Causa: Tu aplicación corre en un dominio que no está en la configuración CORS de la API.

Solución: Usa Bearer Token en su lugar, que no depende de dominios autorizados.

3. Las cookies están bloqueadas por seguridad

Causa: Tu navegador o herramienta está bloqueando las cookies por políticas de seguridad o privacidad.

Solución:

• Revisa la configuración de privacidad de tu navegador o herramienta.
• Permite cookies para el dominio de la API.
• Si no puedes cambiar la configuración, usa Bearer Token en su lugar.