Referencia de la API · v1
Autenticación y ámbitos
Cómo se autentica la API de XEYE: cabecera X-API-Key, ámbitos de cada clave, caducidad, rotación y límites de peticiones.
La cabecera X-API-Key
Toda petición lleva la cabecera X-API-Key con una clave creada en la consola (Claves API). No hay OAuth ni tokens que renovar: la clave se envía tal cual, siempre sobre HTTPS. El backend guarda solo su hash y una clave borrada deja de funcionar en la siguiente petición.
GET https://api.xeye.es/v1/me
X-API-Key: xeye_Wq3kAbcdefghijklmnopqrstuvwxyz01Una clave pertenece a una cuenta: ve y modifica únicamente las listas de esa cuenta. Un recurso de otra cuenta responde 404, nunca 403, para no revelar que existe.
Ámbitos: qué puede hacer cada clave
Al crear una clave eliges sus ámbitos. Cada endpoint exige uno concreto; sin él, 403 API_KEY_SCOPE. Los de escritura implican el de lectura del mismo recurso. Las claves creadas antes de la API de gestión tienen solo search.
| Ámbito | Permite | Implica |
|---|---|---|
| search | Buscar en las listas públicas de la cuenta (POST /search, POST /target). | — |
| lists:read | Leer listas y elementos. | — |
| lists:write | Crear, modificar y borrar listas y elementos. | lists:read |
| trainings:read | Consultar entrenamientos, estimaciones y modelos. | — |
| trainings:write | Lanzar y relanzar entrenamientos (consumen crédito). | trainings:read |
La consola ofrece dos preajustes: «Solo búsqueda» (search), para la clave que usa tu web, y «Gestión completa» (todos), para el proceso que sincroniza el catálogo. Lo más seguro es una clave por uso.
Caducidad
Opcionalmente, una clave caduca en una fecha fija (de 1 a 3650 días desde su creación). Una clave caducada responde 401 API_KEY_EXPIRED; la caducidad no se edita: crea otra clave y borra la vieja. La consola muestra la fecha y el último uso de cada clave.
Comprobar una clave: GET /me
Identidad de la clave
https://api.xeye.es/v1/meÁmbito: cualquier claveDevuelve el id y el prefijo de la clave, sus ámbitos efectivos (con los implícitos), la caducidad y el id de la cuenta. No exige ningún ámbito: sirve para verificar la configuración antes de tocar datos.
Petición
curl -X GET https://api.xeye.es/v1/me \
-H "X-API-Key: $XEYE_API_KEY"Respuesta
{
"api_key_id": 7,
"prefix": "xeye_Wq3kAbc",
"scopes": ["lists:read", "lists:write", "trainings:read", "trainings:write"],
"expires_at": null,
"user_id": 3
}Rotación y revocación
Rotar es crear una clave nueva con los mismos ámbitos, desplegarla y borrar la antigua: ambas conviven mientras tanto. Borrar una clave la revoca al instante. Si una clave se filtra, bórrala y revisa el historial de búsquedas de tus listas.
Límites de peticiones
La API de gestión admite 300 peticiones por minuto y clave. Cada respuesta autenticada lleva X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset (segundos hasta la siguiente ventana); al agotarse recibes 429 RATE_LIMITED con Retry-After.
Además, 30 fallos de autenticación por minuto desde la misma IP bloquean esa IP el resto del minuto (429), antes de consultar nada. La búsqueda tiene su propio cupo por cuenta: 120 por minuto, compartido por todas las claves.
HTTP/1.1 429 Too Many Requests
Retry-After: 23
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 23
{
"status": 429,
"error": "Too Many Requests",
"code": "RATE_LIMITED",
"message": "Too many requests, try again in 23 seconds"
}Recomendaciones
Guarda la clave en una variable de entorno del servidor; nunca en el repositorio ni en código que llegue al navegador.
Una clave por integración y entorno, con los ámbitos mínimos: la de la web solo search; la del sincronizador, sin search.
Pon caducidad a las claves de pruebas y de terceros, y revisa el último uso de cada una en la consola.