# Autenticación y claves de API

> Cómo crear, usar y proteger las claves que autentican la API /v1.

## Crear la clave en el panel

En **Claves de API → Crear clave**, completa:

| Campo | Qué es |
|---|---|
| **Nombre** | Hasta 32 caracteres, para reconocer la clave después (`produccion`, `crm`) |
| **Permisos** | `send` (enviar mensajes), `read` (leer conexiones, conversaciones y logs), `templates` (crear y editar plantillas) y `admin` (todo). Marca solo lo que usa la integración |
| **Conexiones** | **Todas las conexiones** o solo las seleccionadas. Una clave limitada a conexiones no ve las demás |
| **Validez** | 30, 90, 180 o 365 días, o **No vence** |
| **Límite por minuto** | De 1 a 6000 solicitudes por minuto (predeterminado: 600). Consulta [Límites](/es/api/limits/) |

Propietario, admin y dev crean claves. Solo propietario y admin otorgan el permiso `admin`. Una vez creada, la clave se puede editar (nombre, permisos, conexiones, límite), desactivar, reactivar o revocar.

## Tipos de clave

|  | Clave de organización (`mj_`) | Clave de conexión (`mjc_`) |
|---|---|---|
| Dónde crearla | **Claves de API**, a nivel de organización | Pestaña **Claves de API** de la conexión |
| Alcance | Cualquier conexión de la org; `connection_id` obligatorio en las rutas de mensajes | Solo su conexión; `connection_id` es opcional (si se envía y es distinto, 403 [`connection_not_allowed`](/es/errors#connection_not_allowed)) |
| Destinos | Globales y de cualquier conexión | Solo los de su conexión, nunca globales |
| Conexiones | Listar, modificar y desconectar | Leer y modificar la propia; no desconecta |
| Enlaces de conexión | Sí | 403 [`organization_key_required`](/es/errors#organization_key_required) |
| Gestionar claves de conexión por `/v1` | Sí, con el permiso `admin` | No |
| Eventos, entregas, logs y costos | Toda la org | Solo los de la conexión (más eventos de la WABA) |
| `GET /v1/me` | `api_key.kind = "org"`, `connection_id` y `connection` nulos | `api_key.kind = "connection"`, con `connection_id` y `connection { id, channel, label }` |

Los permisos (`send`, `read`, `templates`, `commerce`, `admin`) valen para ambos tipos. Usa una clave de conexión por integración: solo ve su número y no necesita `connection_id`. Las claves de organización antiguas limitadas a varias conexiones siguen funcionando, pero el panel ya no ofrece esa opción.

Las plantillas, flows y catálogos pertenecen a la WABA: una clave de conexión que los modifica también afecta a las conexiones hermanas de la misma WABA.

## La clave aparece una vez

El valor completo, que empieza con `mj_` (organización) o `mjc_` (conexión), solo aparece en el diálogo de creación. Messajo guarda solo un hash: ni el panel ni el soporte pueden mostrarla de nuevo. ¿La perdiste? Crea otra y revoca la anterior.

Para reconocer la clave después, el panel muestra el **prefijo visible**, sus primeros 10 caracteres (por ejemplo, `mj_A1b2c3d`). El mismo prefijo vuelve en el campo `api_key.start` de `GET /v1/me`.

## Authorization: Bearer

Envía la clave en el encabezado `Authorization` con el esquema `Bearer`, en cada solicitud:

```bash
curl https://api.messajo.com/v1/me \
  -H "Authorization: Bearer $MESSAJO_API_KEY"
```

La cookie de sesión del panel **nunca** autentica la API `/v1`: una solicitud solo con cookie recibe [`missing_api_key`](/es/errors#missing_api_key). Tampoco se acepta la clave en la query string.

## Errores de autenticación

Todo error usa el cuerpo único de la API, con un `code` estable:

```json
{
  "error": {
    "code": "missing_api_key",
    "message": "Missing API key: send Authorization: Bearer <key>",
    "meta_code": null,
    "retryable": false,
    "request_id": "req_0193a1b2c3d47e8f9a0b1c2d3e4f5a6b",
    "docs_url": "https://docs.messajo.com/errors#missing_api_key"
  }
}
```

| Estado | `code` | Cuándo |
|---|---|---|
| 401 | [`missing_api_key`](/es/errors#missing_api_key) | Falta el encabezado `Authorization: Bearer` |
| 401 | [`invalid_api_key`](/es/errors#invalid_api_key) | La clave no existe o fue revocada |
| 401 | [`api_key_expired`](/es/errors#api_key_expired) | La clave venció |
| 401 | [`api_key_disabled`](/es/errors#api_key_disabled) | La clave fue desactivada en el panel |
| 403 | [`insufficient_permissions`](/es/errors#insufficient_permissions) | La clave no tiene el permiso que exige la ruta |
| 403 | [`connection_not_allowed`](/es/errors#connection_not_allowed) | La clave está limitada a otras conexiones |
| 403 | [`organization_key_required`](/es/errors#organization_key_required) | La ruta es solo de clave de organización y la clave es de conexión |

Ninguno de estos errores se resuelve repitiendo la llamada (`retryable: false`): corrige la clave o sus permisos.

## Probar en el /reference

La referencia interactiva está en `https://api.messajo.com/reference`.Allí pegas la clave en **Authentication** y usas **Test request** para llamar las rutas de verdad, como `GET /v1/me`.

La llamada sale de tu navegador hacia el propio servidor, en el mismo origen, sin pasar por proxies de terceros. La [referencia de esta documentación](/es/reference) es solo de lectura y no envía solicitudes.

## Rotar una clave

En el panel, **Rotar** crea una clave nueva con el mismo nombre, tipo, permisos, conexión y límite, y muestra el valor nuevo una sola vez. La clave anterior sigue valiendo durante una **gracia**: **24 horas** (predeterminado) o **ahora**, que la termina al instante. La gracia nunca supera la validez original. Una clave desactivada o vencida no se puede rotar.

Por `/v1`, una clave de organización con `admin` crea, rota y revoca solo **claves de conexión** (`grace`: `24h` o `now`). Las claves de organización se rotan en el panel; `/v1` devuelve 404 `not_found` para ellas:

```bash
# crear la clave de una conexión
curl -X POST https://api.messajo.com/v1/connections/$CONNECTION_ID/api-keys \
  -H "Authorization: Bearer $MESSAJO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "crm", "permissions": ["send", "read"]}'

# rotar
curl -X POST https://api.messajo.com/v1/api-keys/$KEY_ID/rotate \
  -H "Authorization: Bearer $MESSAJO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"grace": "24h"}'

# revocar
curl -X DELETE https://api.messajo.com/v1/api-keys/$KEY_ID \
  -H "Authorization: Bearer $MESSAJO_API_KEY"
```

La respuesta de la rotación trae el secreto nuevo y `previous_key_expires_at`, el fin de la gracia de la anterior. Los campos completos están en la [referencia](/es/reference).

## Buenas prácticas

- **Variable de entorno o gestor de secretos**, nunca en el código ni en el repositorio.
- **Nunca en el navegador ni en la app móvil.** Cualquiera extrae una clave de un front-end. Llama a Messajo desde tu back-end.
- **Una clave por integración**, con los permisos mínimos y, si se puede, limitada a las conexiones que usa. Si una se filtra, revocas solo esa.
- **Validez definida** para claves de prueba y de terceros.
- **Rotar sin cortes:** crea la clave nueva, cámbiala en la integración, revisa el **último uso** de la anterior en el panel y recién entonces revócala. El **último uso** se actualiza como máximo cada ~5 s por réplica y el contador de solicitudes no es exacto por llamada (la verificación de la clave se cachea 5 s).
- **¿Se filtró?** Revócala de inmediato. La siguiente llamada con ella ya recibe [`invalid_api_key`](/es/errors#invalid_api_key).

## X-Request-Id para soporte

Toda respuesta, de éxito o de error, trae el encabezado `X-Request-Id` (`req_…`). El mismo valor aparece en `request_id` en el cuerpo de los errores y de `GET /v1/me`.

Guarda ese valor en el log de tu integración. Al pedir ayuda, envía el `X-Request-Id`: con él, el soporte encuentra la llamada exacta sin que tengas que enviar la clave.
