Autenticación

Introducción

La API de Aleluya soporta diferentes métodos de autenticación según el contexto y tus necesidades. Esta guía explica en detalle cómo funciona cada método y cuándo usar cada uno.

Conceptos importantes

Antes de comenzar, es importante entender algunos conceptos clave que usarás en ambos métodos de autenticación.

¿Qué es el api_token?

El api_token es un código especial que identifica tu cuenta de forma única en la API. Es como una "llave" que te permite acceder a tus datos.

¿Cuándo lo necesitas?

• Obligatorio si quieres usar el método de Bearer Token
• Opcional si usas el método de Cookies (puedes usar tu contraseña en su lugar)

Cómo obtener tu api_token

Hay dos formas de obtener tu api_token:

Opción 1: Al crear tu cuenta (registro)

Cuando creas una cuenta nueva con POST /v1/registries, el api_token se devuelve automáticamente en la respuesta junto con tu información de usuario y empresa. Guarda este token porque lo necesitarás más adelante.

Ejemplo de respuesta del registro:

{
  "data": {
    "user": {
      "id": "3a4b8cc7-fb8c-4eac-94fb-c0b6b39bbcf1",
      "email": "[email protected]",
      "api_token": "9d459233974f1500aa79d94f550c2694"
    },
    "company": {
      "id": "32668bfe-78a4-498d-a62b-3e8c1693d723",
      "name": "Mi Empresa"
    }
  }
}

Opción 2: Desde la interfaz de Aleluya

Si ya tienes acceso a la interfaz web de Aleluya, puedes obtener tu api_token directamente desde ahí:

Pasos a seguir:

1. Dirígete al módulo Integraciones en tu cuenta de Aleluya
2. Ubícate en la sección "Integración por API"
3. En este módulo encontrarás tus credenciales, específicamente:
   • Tu username (que es tu email)
   • Tu api_token

Estas credenciales son las que usarás para generar el código de autorización Basic que necesitas para autenticarte en la API.

Método 1: Autenticación con 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.

Paso 1: Cómo 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

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á.

Método 2: Autenticación con Bearer Token

Este método es ideal cuando necesitas más control sobre cómo se maneja la autenticación. A diferencia de las cookies, debes guardar y enviar el token manualmente en cada petición.

Paso 1: Cómo iniciar sesión para obtener Bearer Token

Para obtener un Bearer Token, debes modificar tu petición de login de la siguiente forma:

1. Usar tu api_token (no tu contraseña) en el Basic Auth del login.
2. Enviar auth_type: 'bearer' en el body de la petición para indicarle a la API que quieres un Bearer Token.

Cómo codificar tus credenciales

Debes usar tu api_token en lugar de tu contraseña:

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

🚧

Para usar Bearer Token, debes usar tu api_token en el Basic Auth, no tu contraseña. Si usas tu contraseña, no recibirás el Bearer Token.

Ejemplo de petición de login

curl --location --request POST 'https://nominapp-api-stage.herokuapp.com/v1/sessions' \
--header 'Authorization: Basic dXN1YXJpb0BlamVtcGxvLmNvbTo5ZDQ1OTIzMzk3NGYxNTAwYWE3OWQ5NGY1NTBjMjY5NA==' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
  "auth_type": "bearer"
}'

Paso 2: Qué recibes después del login

Cuando inicias sesión exitosamente con auth_type: 'bearer', la API te devuelve un api_access_token directamente en el body de la respuesta JSON. Este es el token que usarás para autenticar todas tus peticiones siguientes.

Respuesta del login

A diferencia del método de Cookies, aquí sí recibes el token en el body de la respuesta:

{
  "data": {
    "user": {
      "id": "3a4b8cc7-fb8c-4eac-94fb-c0b6b39bbcf1",
      "email": "[email protected]",
      ...
    },
    "api_access_token": "eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaEpJaWxrWmpJME5qYzVZaTB4TmpZM0xUUXhNVE10T0RZMk1pMDJNVEUyTmpnMk1qWXhZamNHT2daRlZBPT0iLCJleHAiOiIyMDI1LTAxLTE1VDEwOjAwOjAwLjAwMFoiLCJwdXJwb3NlIjoiYXBpX2FjY2VzcyJ9fQ==",
    "api_access_token_expires_at": "2025-01-15T10:00:00.000Z",
    "created_at": 1764301434981,
    "is_new_user": false
  }
}

🚧

Guarda el api_access_token que recibes, lo necesitarás para todas tus peticiones siguientes.

Características del Bearer Token

El api_access_token que recibes tiene estas características:

• Duración: El token es válido por 8 horas. Después de ese tiempo, expira y necesitas obtener uno nuevo.
• Formato: Es un token JWT firmado (un tipo de token seguro y estándar).
• Propósito: Se crea específicamente para acceso a la API.
• Renovación: Cuando expire, debes iniciar sesión nuevamente para obtener un nuevo token.

Paso 3: Cómo hacer peticiones siguientes

Una vez que recibes el api_access_token, debes incluirlo manualmente en cada petición que hagas a la API. A diferencia de las cookies, aquí tú tienes el control total sobre cuándo y cómo enviar el token.

Formato del header

Debes agregar un header llamado Authorization con el valor Bearer seguido de un espacio y luego tu token:

Authorization: Bearer <tu_api_access_token>

🚧

No olvides incluir la palabra "Bearer" seguida de un espacio antes del token. Es parte del formato requerido.

Ejemplo de petición

curl --location --request GET 'https://nominapp-api-stage.herokuapp.com/v1/economic_sectors' \
--header 'Authorization: Bearer eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaEpJaWxrWmpJME5qYzVZaTB4TmpZM0xUUXhNVE10T0RZMk1pMDJNVEUyTmpnMk1qWXhZamNHT2daRlZBPT0iLCJleHAiOiIyMDI1LTAxLTE1VDEwOjAwOjAwLjAwMFoiLCJwdXJwb3NlIjoiYXBpX2FjY2VzcyJ9fQ==' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json'

🚧

En cada petición, incluye Authorization: Bearer <tu_token> en los headers. Sin esto, la API no sabrá quién eres y rechazará tu petición.

Ventajas del Bearer Token

• ✅ Flexibilidad: Funciona en cualquier contexto.
• ✅ Control: Tienes control total sobre cuándo y cómo usar el token.
• ✅ Independiente del cliente: No depende de soporte de cookies.
• ✅ Ideal para APIs: Perfecto para integraciones entre servicios.

Limitaciones del Bearer Token

• ⚠️ Manejo manual: Debes guardar y enviar el token manualmente.
• ⚠️ Expiración: El token expira en 8 horas.
• ⚠️ Sin refresh token: A diferencia de las cookies, el Bearer Token no tiene un mecanismo de refresh token. Debes iniciar sesión nuevamente cada vez que expire.

Errores comunes

Error 401: No autorizado

¿Qué significa este error?

La API rechaza tu petición porque no pudo verificar tu identidad. Esto puede suceder por varias razones relacionadas con tus credenciales o tokens de sesión.

Causas y soluciones:

1. Token expirado

Causa: Tu sesión ha expirado porque pasó mucho tiempo desde que iniciaste sesión.

Solución:

• Si usas Cookies: El token expira en 4 horas. Inicia sesión nuevamente para obtener nuevas cookies.
• Si usas Bearer Token: El api_access_token expira en 8 horas. Inicia sesión nuevamente para obtener un nuevo token.

2. Token inválido

Causa: El token que estás usando no es válido o ya no existe.

Solución:

• Verifica que estés usando el token correcto y más reciente.
• Si usas Bearer Token, asegúrate de usar el api_access_token que recibiste en tu último login exitoso.
• Si usas Cookies, verifica que las cookies no hayan sido eliminadas o modificadas.

3. Cookies no enviadas

Causa: Si usas el método de Cookies, tu herramienta no está enviando las cookies con la petición.

Solución:

• En Postman: Las cookies se envían automáticamente después del login. Verifica que hayas iniciado sesión correctamente.
• En navegadores: Verifica que las cookies no estén bloqueadas por configuración de privacidad.

4. Bearer Token mal formado

Causa: Si usas Bearer Token, olvidaste incluir la palabra "Bearer" o el formato del header no es correcto.

Solución:

• Asegúrate de que el header sea exactamente así: Authorization: Bearer <tu_token>
• Debe incluir la palabra "Bearer" seguida de un espacio y luego tu token.
• Ejemplo correcto: Authorization: Bearer eyJfcmFpbHMiOnsibWVzc2FnZSI6...

No recibo el Bearer Token después del login

¿Qué significa este problema?

Haces el login pero no ves el campo api_access_token en la respuesta JSON. Esto significa que la API no generó el Bearer Token.

Causas y soluciones:

1. Estás usando tu contraseña en lugar de tu api_token

Causa

Para obtener un Bearer Token, debes usar tu api_token en el Basic Auth, no tu contraseña.

Solución

• Usa tu api_token (no tu contraseña) en el Basic Auth del login.
• El formato debe ser: email:api_token codificado en Base64.

2. Olvidaste enviar auth_type: 'bearer'

Causa

No incluiste el parámetro auth_type: 'bearer' en el body de la petición de login.

Solución

• Asegúrate de incluir {"auth_type": "bearer"} en el body de la petición POST /v1/sessions.
• Sin este parámetro, la API asume que quieres usar Cookies y no devuelve el Bearer Token.

3. Tu usuario no tiene un api_token válido

Causa

Tu cuenta de usuario no tiene un api_token asignado o es inválido.

Solución

• Verifica que tu usuario tenga un api_token válido.
• Puedes obtenerlo cuando creas tu cuenta (en la respuesta de POST /v1/registries).
• Si ya estás autenticado, puedes consultarlo con GET /v1/users/token o regenerarlo con PATCH /v1/users/token.
• También puedes obtenerlo desde la interfaz web de Aleluya en el módulo de Integraciones.

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. 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.