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.

Métodos de autenticación

Autenticación por Cookies

El método más simple. Al iniciar sesión, la API establece cookies de sesión que se envían automáticamente en cada petición siguiente. No necesitas manejar tokens manualmente.

• Ideal para: Aplicaciones web (frontend) que corran en un dominio autorizado por la API.
• Requisitos: Tu cliente HTTP debe soportar cookies y tu dominio debe estar autorizado en la configuración CORS de la API.

Autenticación por Bearer Token

Un método que te da control total sobre la autenticación. Recibes un token y lo envías manualmente en cada petición.

• Ideal para: Integraciones backend, scripts, servicios externos o cualquier contexto donde no puedas usar cookies.
• Requisitos: Necesitas tu api_token (una credencial exclusiva para la API que se explica más adelante).

¿Qué es el api_token?

El api_token es un código único asociado a tu cuenta. Funciona como una llave exclusiva para la API, similar a una contraseña pero diseñada específicamente para integraciones.

• No expira. Solo cambia si lo regeneras manualmente.
• Es obligatorio para el método de Bearer Token.
• Es opcional para el método de Cookies (puedes usar tu contraseña en su lugar).

Cómo obtener tu api_token

Paso 1: Tener una cuenta

Si aún no tienes cuenta, regístrate con POST /v1/registries:

  curl --location --request POST 'https://nominapp-api-stage.herokuapp.com/v1/registries' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data-raw '{
    "registry": {
      "email": "[email protected]",
      "name": "Tu Nombre",
      "password": "tuPassword123",
      "company_name": "Mi Empresa",
      "company_id_number": "9001234567",
      "phone": "3001234567",
      "payroll_frequency": "monthly",
      "terms_accepted": true
    }
  }'

Ejemplo de respuesta del registro:

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

Paso 2: Regenera tu api_token

Una vez tengas acceso a tu cuenta, regenera tu api_token con:

curl --location --request PATCH 'https://nominapp-api-stage.herokuapp.com/v1/users/token' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json'

Respuesta:

{
  "data": {
    "token": "9d459233974f1500aa79d94f550c2694"
  }
}

🚧

Regenerar el token invalida el anterior. Si tienes integraciones usando el token viejo, dejarán de funcionar. Guarda el nuevo token en un lugar seguro.

Verificar que tienes un token activo

El endpoint GET /v1/users/token muestra una previsualización parcial del token:

curl --request GET 'https://nominapp-api-stage.herokuapp.com/v1/users/token' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json'

Respuesta:

{
  "data": {
    "token_preview": "9**********2694"
  }
}

Esto sirve para confirmar que existe un token asociado a tu cuenta, pero NO devuelve el token completo. Si perdiste tu token, repite el paso 2 para regenerarlo.