Autenticación y seguridad

La cabecera X-Api-Key

Todas las llamadas se autentican con una clave de API en la cabecera X-Api-Key:

curl "https://sandbox-api.saludenruta.es/api/integrations/v1/catalog" \
  -H "X-Api-Key: srd_test_3f9a1c2b_yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy"

Una clave tiene tres partes separadas por guiones bajos:

Sin cabecera, o con una clave desconocida, revocada, caducada o de un proveedor dado de baja, la API responde siempre igual: 401 con el tipo /errors/provider-api/invalid-key. No distinguimos el motivo a propósito, para no dar pistas a quien esté probando claves.

Salud en Ruta guarda solo un resumen criptográfico (SHA-256) de cada clave, no la clave. Por eso se muestra una única vez al crearla y no podemos recuperarla si la pierdes: hay que generar otra.

Ámbitos

Cada clave tiene uno o varios ámbitos que limitan lo que puede hacer. Pide solo los que necesites: una clave que solo consulta estados no debería poder crear avisos.

Una clave válida a la que le falta el ámbito recibe 403 con el tipo /errors/provider-api/scope-missing y el ámbito que falta en el detail («La clave de API no tiene el ámbito visits:write»).

Ciclo de vida de una clave

Las claves las crea, rota y revoca Salud en Ruta desde su intranet, a petición tuya. Escríbenos indicando el prefijo de la clave (nunca la clave completa).

• Alta: con un nombre (para qué sistema es), sus ámbitos, su límite de peticiones por minuto y, si quieres, una fecha de caducidad. La clave completa se te entrega una sola vez, por un canal seguro.
• Rotación: se genera una clave nueva con el mismo nombre, ámbitos, límite y caducidad, y la anterior se revoca en el mismo momento. Coordina con nosotros la hora para desplegar la nueva clave justo a la vez.
• Revocación: con efecto inmediato. No hay caché que mantenga viva una clave revocada: la siguiente petición ya recibe 401.
• Caducidad: si la clave tiene fecha de caducidad, a partir de ese momento responde 401 como una revocada. Avísanos con tiempo para generar la siguiente.

Registramos cuándo y desde qué IP se usó cada clave por última vez, lo que nos ayuda a investigar contigo cualquier uso extraño.

Buenas prácticas

• Solo desde tu servidor. La clave da acceso a los avisos de tu organización: nunca la pongas en una web, una app móvil, un script en el navegador o un repositorio. Si tu front necesita datos, que los pida a tu back, y que tu back llame a la API.
• En un gestor de secretos o en variables de entorno, no en el código ni en ficheros de configuración versionados. Una clave por entorno: srd_test_… en desarrollo y preproducción, srd_live_… solo en producción.
• No la registres. Asegúrate de que tus logs, trazas y herramientas de monitorización no guardan la cabecera X-Api-Key (muchas guardan todas las cabeceras por defecto).
• Mínimos ámbitos, como se explica arriba.
• Rota periódicamente y al cambiar el equipo.

Transporte e IP

• Llama siempre por HTTPS, a las URL base de entornos. No envíes nunca la clave por HTTP sin cifrar.
• Tu cliente HTTP debe verificar el certificado del servidor. No desactives la verificación ni en pruebas.
• Las llamadas a la API pueden venir de cualquier IP: la seguridad depende de la clave, no del origen. Si tu organización necesita salir por un proxy o restringir destinos, autoriza api.saludenruta.es y sandbox-api.saludenruta.es.
• Los webhooks que te enviamos salen de los servidores de Salud en Ruta. No te recomendamos filtrar por IP (pueden cambiar sin aviso): la garantía de que una entrega es nuestra es la firma.

Si una clave se filtra

Si sospechas que una clave ha quedado expuesta (se ha subido a un repositorio, ha aparecido en un log compartido, la tenía alguien que ya no está):

1. Escríbenos de inmediato a info@saludenruta.es con el asunto «Clave comprometida» y el prefijo de la clave. Si es urgente, llama además a la centralita (+34 611 673 280).
2. La revocamos al momento y te entregamos una nueva (rotación). Despliega la nueva en tu sistema.
3. Revisa juntos el uso: te diremos cuándo y desde qué IP se usó la clave por última vez para que compruebes si hubo llamadas que no reconoces.
4. Elimina la clave del sitio donde se filtró (el historial de git también) y revisa cómo llegó allí.

El secreto de un webhook se trata igual: si se filtra, pídenos que lo rotemos.