Autenticación

Todos los endpoints del API —excepto el health check— requieren autenticación mediante una clave de API que se envía en el header ApiKey.

El header ApiKey

ApiKey: <tu-clave-secreta>

La clave es un secreto compartido entre Jaremar y Hosana. Hosana la entrega por un canal seguro. Nunca debe viajar en la URL, en query params, ni quedar registrada en logs del lado de Jaremar.

Cuidado con el nombre del header

El header se llama exactamente ApiKey (sin guion, sin espacios). No es Api-Key, ni Authorization, ni X-Api-Key. Si lo envías con otro nombre, el servidor responderá 401.

Comparación segura

El servidor compara la clave recibida contra la configurada usando comparación de tiempo constante (hash_equals), de modo que no se puede inferir la clave por diferencias de tiempo de respuesta.

Respuestas de autenticación

HTTP	Situación	Cuerpo
401	Falta el header ApiKey.	{ "success": false, "message": "ApiKey requerido. Incluya el header ApiKey en su solicitud." }
401	El ApiKey enviado no coincide con el configurado.	{ "success": false, "message": "ApiKey inválido." }
503	El servidor no tiene configurada una clave (error de servidor).	{ "success": false, "message": "El servidor no está configurado para recibir solicitudes API." }

Nota

Un 503 no es un problema de tu lado: significa que Hosana aún no terminó de configurar la clave en el servidor. Reporta el caso a Hosana en lugar de reintentar.

Ejemplo

curl -X GET "https://<dominio-hosana>/api/v1/ping" \
  -H "ApiKey: TU_CLAVE_AQUI"

El endpoint ping no exige ApiKey, pero incluirlo no causa error y sirve para probar que tu cliente lo está enviando correctamente antes de llamar a los endpoints protegidos.