Autenticación por 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 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).
• Renovación: Cuando expire, debes iniciar sesión nuevamente para obtener un nuevo token. No hay refresh token.

Paso 3: Cómo hacer peticiones siguientes

Una vez que recibes el api_access_token, debes incluirlo 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.

Renovación del token

El api_access_token expira cada 8 horas. No existe un mecanismo de refresh token. Cuando expire, repite el Paso 1 para obtener uno nuevo.

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

Causa: El api_access_token expiró (pasaron más de 8 horas) o el header está mal formado.

Solución:

• Haz login de nuevo para obtener un nuevo api_access_token.
• Verifica que el header sea exactamente Authorization: Bearer <token> (con la palabra "Bearer", un espacio, y luego el token).

No recibo el api_access_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. Si usas tu contraseña, el login funciona pero devuelve cookies en lugar del Bearer Token.

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.