Flujo OAuth 2.0 Client Credentials

Diagrama del flujo

Paso 1: Obtener el Access Token

Antes de hacer cualquier request a la API, necesitas obtener un access token.

Request (estructura)

Haz un POST al endpoint de autenticación con las siguientes credenciales:

POST {auth_url}/oauth/token
Content-Type: application/x-www-form-urlencoded

client_id=<tu_client_id>
&client_secret=<tu_client_secret>
&audience=https://connect.quralo.com
&grant_type=client_credentials

Ejemplo con curl (Sandbox)

curl -X POST https://auth.connect.sandbox.quralo.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "audience=https://connect.quralo.com" \
  -d "grant_type=client_credentials"

Ejemplo con JSON

{
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "audience": "https://connect.quralo.com",
  "grant_type": "client_credentials"
}

Si usas una librería HTTP (Node.js, Python, etc.), envía esto en el body del POST.

Paso 2: Respuesta exitosa

Si las credenciales son válidas, recibirás:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IlFUTXhSVEU1T0VReE16RkdNRFIyTURORk0wSXhOakJGTURkRk9WQTROVEV4UXpkQlJFRkMifQ.eyJpc3MiOiJodHRwczovL2F1dGguc2FuZGJveC5jb25uZWN0LnF1cmFsby5jb20vIiwic3ViIjoibkF4MGFiTjVWRUpCRjJJUVFPRjJJbmxjSm51ZHowTDRrXzU4NzM5N0AyaEFJTjNaUG5zVjFIVm45bjd0N00xVndOd2dNV0x2aDVPOFU4PSIsImF1ZCI6Imh0dHBzOi8vY29ubmVjdC5xdXJhbG8uY29tIiwiaWF0IjoxNzE0MDExNDU2LCJleHAiOjE3MTQwOTc4NTYsImF6cCI6Im5BeDAk...truncated",
  "token_type": "Bearer",
  "expires_in": 86400
}

Desglose de la respuesta

Campo	Significado
access_token	Token JWT que usarás en todos los requests. Válido por 24 horas
token_type	Siempre "Bearer" (indica cómo usar el token)
expires_in	Segundos hasta que expire el token (86400 = 24 horas)

Paso 3: Usar el Access Token

Ahora que tienes el token, úsalo en cada request a la API incluyendo el header Authorization:

Authorization: Bearer {access_token}

Ejemplo: Obtener DiagnosticReport

curl -X GET https://connect.sandbox.quralo.com/fhir/r4/DiagnosticReport \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IlFUTXhSVEU1T0VReE16RkdNRFIyTURORk0wSXhOakJGTURkRk9WQTROVEV4UXpkQlJFRkMifQ..."

Formato correcto del header

❌ INCORRECTO:

Authorization: Bearer{token}           // Sin espacio
Authorization: {token}                 // Falta "Bearer"
Authorization: Token {token}           // Tipo incorrecto

✅ CORRECTO:

Authorization: Bearer {access_token}   // Espacio entre Bearer y token

Manejo de Errores

Error 400: Bad Request

Causa: Parámetros faltantes o malformados en el request de token.

{
  "error": "invalid_request",
  "error_description": "Missing required parameter: client_id"
}

Solución: Verifica que incluyes:

• client_id
• client_secret
• audience = https://connect.quralo.com
• grant_type = client_credentials

Error 401: Unauthorized

Causa: Credenciales inválidas o expiradas.

{
  "error": "invalid_client",
  "error_description": "Client authentication failed"
}

Solución:

• Verifica que client_id y client_secret sean correctos
• Asegúrate de estar usando las credenciales del entorno correcto (Sandbox vs Producción)
• Si crees que tus credenciales están comprometidas, contacta a soporte@quralo.com para regenerarlas

Error 403: Forbidden

Causa: Tu aplicación no tiene permiso para acceder al entorno o recurso.

{
  "error": "insufficient_scope",
  "error_description": "Insufficient scope for this resource"
}

Solución: Contacta a soporte@quralo.com para verificar tus permisos.

Error 401 en requests a la API (token inválido)

Causa 1: El access_token está mal formado o faltan caracteres.

Solución: Asegúrate de copiar el token completo, sin truncar.

Causa 2: El token expiró (después de 24 horas).

Solución: Obtén un nuevo token repitiendo el Paso 1.

# El token expiró, obtén uno nuevo
curl -X POST https://auth.connect.sandbox.quralo.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "audience=https://connect.quralo.com" \
  -d "grant_type=client_credentials"

Causa 3: El header Authorization no tiene el formato correcto.

Solución: Verifica que sea exactamente:

Authorization: Bearer {token}

Validación de Token

Si necesitas verificar si un token es válido sin hacer un request a la API, puedes decodificarlo (no es secreto, está firmado pero no encriptado):

# Copiar el token y decodificarlo en: https://jwt.io
# Verifica:
# - "exp": fecha de expiración (en unix timestamp)
# - "aud": debe ser https://connect.quralo.com

Un token válido tiene estructura:

header.payload.signature

Si ves menos de 2 puntos, está malformado.

Flujo de renovación automática

En una integración real, tu aplicación debe:

1. Obtener token al iniciar
2. Almacenar token + expiration_time
3. Antes de cada request:
   - Si token aún es válido (time < expiration_time):
     → Usar token existente
   - Si token expiró:
     → Obtener token nuevo
     → Almacenar nuevo token + expiration_time
     → Usar nuevo token

Esto evita hacer request de token innecesarios.

Postman

Si prefieres no codificar esto a mano, descarga nuestra colección de Postman que automatiza todo este flujo.

Próximos Pasos

• Postman Collection - Prueba sin código
• FHIR R4 - DiagnosticReport - Documentación de recursos

Soporte

¿Preguntas sobre autenticación? Contáctanos en soporte@quralo.com