# 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:


```http
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:


```http
Idempotency-Key: <uuid>
```

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

Consulta: [Idempotencia & Reintentos](/guides/idempotency)

## 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:


```http
X-API-Key: "TU_API_KEY"
```

Ejemplo correcto:


```http
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?

- Generar un QR: [Generar código QR](/guides/generate-qr)
- Manejar errores: [Manejo de errores](/guides/error-handling)
- Ver el contrato completo: [Referencia del API](/apis/qrwey)