AUTHENTICATION

Autenticación con API Key

La API v1 se autentica con la API key de tu workspace, y esa clave solo vale para su propio workspace. Tres llamadas no la piden: GET /config, el workspace de demostración demo y POST /bookings cuando viene de un dominio autorizado para el widget.

Cómo enviar tu API key

Mati acepta dos formatos. Usa el que prefieras, y solo desde tu backend: la clave da acceso de escritura al workspace (reservas, cancelaciones) y en el navegador la ve cualquiera.

Opción 1 — Header dedicado (recomendado)

curl https://app.mati-ia.com/api/v1/workspaces/mi-agenda-mati \
  -H "x-mati-api-key: mat_sk_YOUR_API_KEY"

Opción 2 — Authorization Bearer

curl https://app.mati-ia.com/api/v1/workspaces/mi-agenda-mati \
  -H "Authorization: Bearer mat_sk_YOUR_API_KEY"

Cómo generar tu API key

Inicia sesión en tu dashboard de Mati
Ve a Sistema → API Keys, o directo a /dashboard/[tu-slug]/api-keys. La entrada aparece con el módulo «API para desarrolladores» activo (la prueba de 30 días los incluye todos).
Pulsa Generate API key
La clave queda visible en esa pantalla; puedes volver a copiarla cuando quieras

Importante: el token tiene formato mat_sk_<48 caracteres hex>. Trátalo como una contraseña. Cada workspace tiene una sola clave: al pulsar Regenerate key la anterior deja de funcionar al instante, así que si se filtra, regenerarla es la forma de rotarla.

Límites de uso

Hay dos topes distintos, y se reconocen por el código de respuesta. Los dos se cuentan por dirección IP y pueden contarse por instancia del servidor, así que tómalos como techos y no como cuotas exactas.

Tope	Cuánto	Al pasarte
`POST /bookings`	10 por minuto	429
`PATCH /bookings/{id}` y `POST /bookings/{id}/cancel`	20 por minuto	429
`GET /slots` y `GET /bookings/{id}`	60 por minuto	429
Comprobación de la clave (todas las rutas con clave)	120 peticiones por minuto	401

El último tope no responde 429: la comprobación de la clave falla y la ruta contesta como si la clave no existiera. Si una clave que funcionaba hace un segundo empieza a dar 401 de golpe, espera un minuto antes de regenerarla.

La API no envía cabeceras X-RateLimit-* ni Retry-After: el 429 trae solo { "error": "…" }. Reintenta con una espera creciente.

Errores

Un error trae el texto para una persona en error (en español, puede cambiar de redacción) y un code estable. Decide con el code, no con el texto. La lista completa está en la referencia de la API.

Ejemplo — reserva demasiado cercana (400)

{
  "success": false,
  "error": "Este servicio necesita al menos 1 hora de aviso. La primera hora que se puede reservar es 2027-01-12T09:30:00.000Z.",
  "code": "BOOKING_TOO_SOON"
}

Códigos de estado

Código	Significado
200	OK — request exitoso
400	Bad Request — payload inválido (`VALIDATION_ERROR`) o una regla de reserva rota: `DATE_IN_PAST`, `BOOKING_TOO_SOON`, `BOOKING_TOO_FAR_AHEAD`
401	Unauthorized — API key faltante o inválida, o pasaste el tope de la clave
403	Forbidden — la clave es de otro workspace, el dominio no está autorizado para el widget, o el workspace llegó al límite de su plan
404	Not Found — workspace o recurso no existe (un id de otro workspace también da 404)
409	Conflict — el hueco ya no está libre (`SLOT_UNAVAILABLE`: vuelve a pedir `/slots`) o la reserva no admite el cambio
429	Too Many Requests — pasaste el tope de esa ruta
500	Internal Error — algo se rompió de nuestro lado, repórtalo