Autenticación y entornos

Cada petición se autentica con una API key de tu empresa. La clave decide la empresa, el entorno (live o sandbox) y qué puede hacer (scopes).

Enviar la API key

Usa la cabecera Authorization con el esquema Bearer:

Authorization: Bearer xy_live_AbCd...

Si tu herramienta no permite modificar Authorization, puedes usar X-Api-Key: xy_live_AbCd.... Si llegan las dos, manda Authorization. Sin clave, o con una clave inválida, revocada o caducada, la respuesta es 401 invalid_api_key.

La empresa nunca se envía en la URL ni en el cuerpo: sale de la clave. Un id de otra empresa responde 404, exactamente igual que uno inexistente.

Entornos: live y sandbox

Prefijo de la clave	Entorno	Comportamiento
`xy_live_`	live	Datos reales de la empresa. Las escrituras tienen efecto (notificaciones, calendario...).
`xy_test_`	test (sandbox)	Datos de ejemplo fijos; las escrituras devuelven respuestas plausibles pero no se guardan. Ver Sandbox.

Los dos entornos usan la misma URL base (https://api.xyago.com/v1). Para pasar a producción solo cambias la clave. Cada entorno tiene su propia configuración en el panel (productos habilitados, límite, IPs permitidas, webhooks y secreto de firma).

Crear, rotar y revocar claves

Un administrador gestiona las claves en el panel de xYago → API Developer → Credenciales:

Crear: nombre, entorno, scopes y caducidad opcional. La clave completa se muestra una única vez; xYago solo guarda un hash.
Rotar: genera una clave nueva; la anterior sigue funcionando 24 horas para que puedas desplegar el cambio sin cortes.
Revocar: deja de funcionar de inmediato.

Recomendaciones: una clave por sistema integrado (así el log del panel muestra quién hizo cada petición), solo los scopes necesarios, guárdala en un gestor de secretos o variable de entorno y rótala periódicamente o si sospechas de una filtración.

Scopes

Scope	Permite
`areas:read`	Listar y consultar áreas
`areas:write`	Crear áreas
`employees:read`	Listar y consultar empleados y el estado de las importaciones
`employees:write`	Crear, editar, desactivar e importar empleados
`vacations:read`	Listar solicitudes y consultar saldos de vacaciones
`vacations:write`	Solicitar, aprobar y rechazar vacaciones
`time:read`	Listar tramos de horas
`time:write`	Registrar tramos de horas

Orden de las comprobaciones

En cada petición se comprueba, en este orden, y se responde con el primer fallo:

API key válida → 401 invalid_api_key
Producto habilitado para el entorno de la clave → 403 api_disabled
Endpoint habilitado → 403 endpoint_disabled
Scope en la clave → 403 insufficient_scope
IP de origen permitida → 403 ip_not_allowed (IPs permitidas)
Límite de peticiones → 429 rate_limited (límites)

X-Request-Id

Todas las respuestas llevan X-Request-Id. Puedes enviar el tuyo (8 a 64 caracteres A-Z a-z 0-9 . _ : -, p. ej. el id de la tarea de tu ERP) y se devolverá igual; si no es válido o no lo envías, xYago genera uno (req_...). El id aparece en el log de peticiones del panel: inclúyelo siempre que contactes con soporte.

curl -i "https://api.xyago.com/v1/employees?limit=10" \
  -H "Authorization: Bearer $XYAGO_API_KEY" \
  -H "X-Request-Id: siesa-sync-20260302-0001"

Transporte

Solo HTTPS. Las peticiones se hacen de servidor a servidor: no hay CORS, así que la API no se puede llamar desde un navegador (y no debe: la clave quedaría expuesta).