Configurar mTLS
Configurar mTLS
mTLS (TLS mutuo) es una capa opcional de seguridad para integraciones server-to-server. Tu servidor presenta un certificado cliente al conectarse con Soyio.
mTLS es una funcionalidad enterprise y su disponibilidad depende del plan contratado.
La integración estándar usa HTTPS y una API key, sin certificados cliente. mTLS solo pasa a ser obligatorio para tu cuenta si tu organización solicita exigirlo y Soyio configura esa restricción.
mTLS complementa la API key: cada solicitud sigue usando Authorization: Bearer <secret_jwt>. El certificado no reemplaza el token ni cambia los permisos de la key.
Registrar un certificado
Para confirmar si tu plan incluye mTLS y coordinar su configuración, contacta a soporte@soyio.id.
Para cada entorno necesitas:
- Un certificado cliente X.509 en formato PEM, que Soyio registra para tu organización
- La clave privada correspondiente, disponible en el servidor que envía las solicitudes
- Una API key del mismo entorno
El certificado se registra por separado para sandbox y producción. Al compartir el certificado público con Soyio, indica a qué entorno corresponde.
La clave privada permanece en tu infraestructura. No la compartas con Soyio ni la incluyas en código del navegador o en repositorios.
Hosts por entorno
Las conexiones con mTLS usan estas URLs base:
| Entorno | URL base |
|---|---|
| Sandbox | https://sandbox-mtls.soyio.id/api/v1 |
| Producción | https://app-mtls.soyio.id/api/v1 |
Cada solicitud a estos hosts valida el certificado contra el registrado para tu organización y el entorno de la API key. Esta validación ocurre incluso si tu cuenta todavía permite conexiones sin mTLS.
Probar una conexión
Este ejemplo consulta las API keys de tu organización en sandbox. El permiso api_keys.api.read permite ejecutar esta consulta.
La variable SOYIO_API_SECRET contiene el secret JWT de tu API key de sandbox. Las rutas de --cert y --key corresponden al certificado registrado y a su clave privada.
curl --request GET \
--url 'https://sandbox-mtls.soyio.id/api/v1/api_keys' \
--cert '/ruta/al/certificado-sandbox.pem' \
--key '/ruta/a/la/clave-privada-sandbox.pem' \
--header "Authorization: Bearer $SOYIO_API_SECRET"
Para probar en producción, cambia el host a app-mtls.soyio.id y usa el certificado, la clave privada y el secret de producción.
Exigir mTLS para tu cuenta (opcional)
Registrar un certificado y probar los hosts mTLS no obliga a migrar todas tus integraciones. Mientras tu cuenta no exija mTLS, los hosts habituales sandbox.soyio.id y app.soyio.id siguen aceptando solicitudes con API keys sin certificado cliente.
Si tu organización decide exigir mTLS para sus integraciones server-to-server, coordina ese cambio con Soyio después de probar sandbox y producción.
Al exigir mTLS para tu cuenta, las llamadas con API keys a los hosts habituales se rechazan con 401, aunque el token sea válido. Todas esas integraciones deben usar el host mTLS y presentar el certificado registrado para su entorno.
Renovar o reemplazar un certificado
Soyio identifica el certificado por su huella SHA-256. Un certificado nuevo o renovado debe registrarse antes de usarlo.
Coordina el reemplazo con Soyio y el despliegue en tus servidores. Al cambiar el certificado registrado para un entorno, el anterior deja de ser aceptado. Renovar el certificado no renueva la API key: ambos tienen ciclos de vida separados.
Errores frecuentes
- La conexión TLS falla antes de recibir una respuesta HTTP: revisa que tu cliente pueda leer el certificado y su clave privada, y que ambos correspondan entre sí
401conThis company requires mTLS...: revisa que uses el host mTLS y presentes el certificado cliente, especialmente si tu cuenta exige mTLS401conThe presented client certificate does not match...: el certificado presentado no coincide con el registrado. Comprueba el entorno de la API key y si el certificado fue reemplazado
Los errores 401 anteriores usan type: authentication_error. Si el certificado coincide pero la solicitud sigue fallando, revisa también la autenticación con API keys, los permisos y la guía de errores.