# Autenticación

Cada llamada a `/api/v1` lleva una clave de API en el encabezado `Authorization`. Es el único esquema: igual en esta guía, en la referencia y en los ejemplos.

```http
Authorization: Bearer ruta_ab12cd34ef56_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

Usala **siempre desde tu servidor**, nunca en una página web o una app pública: quien tenga la clave puede crear entregas a tu nombre.

## Formato

| Clave | Entorno |
| --- | --- |
| `ruta_<prefijo>_<secreto>` | Real (producción): entregas reales del courier. |
| `ruta_test_<prefijo>_<secreto>` | De prueba: [espacio aislado](entorno-de-prueba.html). |

El prefijo (12 caracteres) identifica la clave en el panel. Ruta guarda sólo una huella SHA-256 de la clave completa y la compara en tiempo constante: si la perdés, no se puede recuperar; rotala o creá otra.

## Permisos (scopes)

| Permiso | Habilita |
| --- | --- |
| `deliveries:write` | Crear (una o en lote), corregir, cancelar y, con una clave de prueba, simular entregas. |
| `deliveries:read` | Consultar y listar entregas, la etiqueta PDF y las zonas. |
| `proof:read` | El comprobante de entrega con enlaces firmados de 5 minutos. |

Una llamada sin el permiso que necesita recibe `403 API_KEY_SCOPE_MISSING`.

## Claves de toda la empresa y claves de un comercio

- Una **clave de la empresa** ve todas sus entregas, cualquiera sea su origen (panel, app, CSV, formulario de comercio, integración u otra clave), y puede crear entregas para cualquier comercio de la empresa.
- Una **clave de un comercio** sirve para que cada tienda se integre sola: **sólo crea entregas de ese comercio** (si omitís `shipperId` se usa el suyo; otro `shipperId` responde `404`) y **sólo ve las suyas**. Cualquier otra entrega responde `404`, igual que una inexistente.

Ninguna clave ve entregas de otra empresa.

## Rotar y revocar

- **Rotar** genera un secreto nuevo para la misma clave: el anterior deja de funcionar en ese instante. Para cambiar sin cortes, creá una segunda clave, actualizá tu sistema y revocá la primera.
- **Revocar** es definitivo: toda llamada con esa clave recibe `401 API_KEY_REVOKED`.

## Respuestas de autenticación

| Situación | Respuesta |
| --- | --- |
| Falta `Authorization: Bearer …` (o está repetido) | `401 AUTHENTICATION_REQUIRED` |
| Clave mal copiada, inexistente o reemplazada por una rotación | `401 API_KEY_INVALID` |
| Clave revocada | `401 API_KEY_REVOKED` |
| El plan de la empresa no incluye la API | `403 PLAN_FEATURE_UNAVAILABLE` |
| La clave no tiene el permiso de la llamada | `403 API_KEY_SCOPE_MISSING` |