Skip to content
/
Autenticación
Last updated

Autenticación

Todas las solicitudes a la API de QRwey! requieren autenticación mediante una API Key. Esta sección explica cómo usarla correctamente, dónde almacenarla y cómo evitar errores comunes.

Header requerido

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.

Dónde usar la API Key

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

Uso correcto

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

Uso incorrecto (NO permitido)

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

Ambientes (DEV y PROD)

QRwey! opera con ambientes separados:

  • Desarrollo / Pruebas: https://api-dev.qrwey.com
  • Producción: https://clients.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

Operaciones con Idempotency-Key

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

Errores comunes

401 Unauthorized

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

Rotación y revocación de API Keys

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

Buenas prácticas adicionales

  • 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

¿Qué sigue?

Previous page
Next page