Autenticación

QRwey! utiliza dos esquemas de autenticación según el tipo de integración:

• X-API-Key — lo usan los Comercios para consumir los endpoints de generación y resolución de QR. Esta guía cubre ese esquema.
• Authorization: Bearer {access_token} (OAuth 2.0) — lo usan los Integradores para consumir la Gestión de Clientes (administración de grupos, emisores, comercios, y timbrado directo de CFDI). Consulta Gestión de Clientes.

Los Integradores son quienes mantienen la relación comercial con QRwey!: crean grupos, dan de alta emisores (RFCs ante el SAT) y registran los comercios bajo cada emisor. A cada comercio le emiten la X-API-Key que describe esta guía.

Esta sección explica cómo usar X-API-Key correctamente, dónde almacenarla y cómo evitar errores comunes.

QRwey! utiliza un esquema simple de autenticación basado en headers HTTP.

Todas las peticiones deben incluir:

X-API-Key: TU_API_KEY

Este header es obligatorio tanto en lecturas como en operaciones de escritura.

La API Key de QRwey! es una credencial sensible y debe manejarse con cuidado.

• ✅ Backend (server-to-server)
• ✅ Servicios internos
• ✅ Jobs o workers

• ❌ Frontend (React, Vue, Angular, etc.)
• ❌ Aplicaciones móviles
• ❌ URLs o query parameters
• ❌ Repositorios de código
• ❌ Logs públicos

⚠️ Regla simple: si el usuario puede verla, está comprometida.

QRwey! opera con ambientes separados:

• Desarrollo / Pruebas: https://api-dev.qrwey.com
• Producción: https://api.qrwey.com

Recomendaciones importantes:

• Las API Keys suelen ser distintas por ambiente
• No mezcles una API Key de DEV con el host de PROD
• Un error de ambiente normalmente resulta en 401 Unauthorized

Esta sección es exclusiva para los Integradores de QRwey!. Los Comercios que solo generan y resuelven QR no necesitan un token: usan el header X-API-Key descrito arriba.

Los Integradores consumen la Gestión de Clientes con Authorization: Bearer {access_token} (OAuth 2.0, flujo client credentials). El access_token se obtiene del servidor de autenticación de QRwey! con una petición POST.

• Desarrollo / Pruebas: https://auth-dev.qrwey.com/auth/realms/petrovol/protocol/openid-connect/token
• Producción: https://auth.qrwey.com/auth/realms/qrwey/protocol/openid-connect/token

La petición es POST con Content-Type: application/x-www-form-urlencoded y los siguientes campos en el cuerpo:

Ejemplo con curl (ambiente de desarrollo):

curl -X POST \
  'https://auth-dev.qrwey.com/auth/realms/petrovol/protocol/openid-connect/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'client_id=TU_CLIENT_ID' \
  -d 'client_secret=TU_CLIENT_SECRET' \
  -d 'grant_type=client_credentials'

{
  "access_token": "eyJhbGciOiJSUzI1NiIsI-Ro5_QhgBNGDpGznTERiFLGyqtHeSeDF2od4KsSqwxXPoVmfq342G2zDkw4tblrJ3h6bI97oCHuoq6_F8SKIN8SjKZBzcYxGiUE26yodtjPAqbx29Dw08Tg",
  "expires_in": 2419200,
  "refresh_expires_in": 0,
  "token_type": "Bearer",
  "not-before-policy": 0,
  "scope": "profile email"
}

Usa el valor de access_token en el header Authorization de cada petición a la Gestión de Clientes:

Authorization: Bearer {access_token}

El campo expires_in indica la vigencia del token en segundos; solicita uno nuevo cuando esté por expirar. Trata el client_secret y el access_token como credenciales sensibles: aplican las mismas reglas de manejo que la X-API-Key (nunca en frontend, URLs, logs públicos ni repositorios de código).

Para operaciones de escritura (por ejemplo, generar un QR), además de X-API-Key es obligatorio enviar:

idempotency-key: <uuid>

Este header evita que se creen transacciones duplicadas en caso de reintentos.

Consulta: Idempotencia & Reintentos

Este error indica que la solicitud no pudo autenticarse.

Causas frecuentes:

• X-API-Key ausente
• API Key inválida o revocada
• API Key no corresponde al ambiente
• Espacios o comillas al copiar la key

Ejemplo incorrecto:

X-API-Key: "TU_API_KEY"

Ejemplo correcto:

X-API-Key: TU_API_KEY

Buenas prácticas recomendadas:

• Rota tus API Keys de forma periódica
• Mantén dos keys activas durante una migración, si es posible
• Revoca inmediatamente una key comprometida
• Monitorea respuestas 401 como indicador de incidentes

• Usa variables de entorno o un secret manager
• Nunca hardcodees la API Key
• Limita el acceso a las keys por equipo o servicio
• Registra errores de autenticación para depuración

• Generar un QR: Generar código QR
• Manejar errores: Manejo de errores
• Ver el contrato completo: Referencia del API