Envías una solicitud a una API de un socio, envías una solicitud bien formada con un token válido y aun así recibes un error de handshake TLS. El endpoint no te pide tu clave API. Le pide a tu cliente que demuestre quién es con un certificado, incluso antes de que cualquier solicitud HTTP salga de tu máquina. Eso es TLS mutuo, y si nunca lo has configurado en una herramienta de pruebas, puede retrasar una integración por un día.
Esta guía te explica cómo configurar certificados de cliente y certificados CA en Apidog para que puedas probar una API protegida con mTLS sin luchar con el handshake. Añadirás un certificado y clave de cliente para un host específico, adjuntarás un certificado CA para que las raíces auto-firmadas dejen de generar errores, y enviarás una solicitud autenticada que Apidog firmará automáticamente. Si los errores de certificado son un territorio nuevo, el manual sobre la verificación de certificados SSL merece la pena leerlo junto con este. Para el protocolo en sí, la referencia de MDN TLS es una explicación sólida e independiente del proveedor.
Qué es el TLS mutuo y por qué algunas APIs lo exigen
HTTPS regular es una confianza unidireccional. El servidor presenta un certificado, tu cliente lo verifica y la conexión se cifra. El servidor no tiene ninguna prueba criptográfica de quién eres; para eso, se basa en un token o clave API dentro de la solicitud.
El TLS mutuo hace que la confianza sea bidireccional. El servidor sigue presentando su certificado, pero también le pide al cliente que presente uno. Si tu certificado no está firmado por una autoridad de certificación en la que confía el servidor, el handshake falla y la conexión nunca se abre. No pasa el cuerpo de la solicitud, ni los encabezados, nada.
Te encontrarás con la autenticación TLS mutua (mTLS) en lugares donde un token de portador filtrado no es un modo de fallo aceptable:
- Banca y pagos. Las APIs de banca abierta y los procesadores de tarjetas a menudo requieren un certificado de cliente emitido a tu organización además de OAuth. La documentación de Stripe describe este tipo de modelo de credenciales por capas para endpoints financieros sensibles.
- Tráfico interno y de servicio a servicio. Las empresas que ejecutan una red de confianza cero hacen que los servicios demuestren su identidad con certificados en lugar de confiar en el perímetro de la red.
- APIs de socios B2B. Un socio puede emitirte un certificado de cliente durante la incorporación para que solo tus máquinas registradas puedan acceder a sus endpoints.
Si OAuth también está en juego, los dos se combinan limpiamente; RFC 8705 formaliza cómo el TLS mutuo vincula un token OAuth a un certificado de cliente. El certificado es una credencial de capa de red, separada de la autenticación de capa de aplicación en tu solicitud. Esa distinción importa en Apidog, y es lo que la gente a menudo se confunde. Los certificados gestionan mTLS. La pestaña Autorización gestiona las claves API, los tokens de portador, OAuth y la autenticación Básica. A menudo necesitas ambos a la vez, pero los configuras en lugares diferentes.
Cómo Apidog delimita los certificados por host
Apidog maneja tanto los certificados CA como los certificados de cliente, y los configura globalmente en lugar de por solicitud. Configuras un certificado una vez, lo vinculas a un host, y Apidog lo adjunta automáticamente en cada solicitud HTTPS que coincida con ese host. No hay un interruptor por solicitud que recordar ni una cabecera que pegar.
Dos tipos de certificados realizan dos trabajos diferentes:
- Un certificado de cliente es lo que presentas para demostrar tu identidad para la autenticación TLS mutua. Es la credencial que solicita la API del socio.
- Un certificado CA le indica a Apidog que confíe en una autoridad de certificación que aún no conoce. Apúntalo a tu CA raíz interna y el temido
SSL Error: Self signed certificatedesaparecerá, porque Apidog ahora confía en los endpoints firmados por esa autoridad.
La clave de alcance es el host. Cada certificado de cliente está vinculado a un dominio, y Apidog compara el host de la solicitud saliente con esa vinculación. Si el host es correcto, todo lo demás es automático. Si es incorrecto, Apidog no envía nada en silencio, porque nunca encontró una coincidencia.
Configura un certificado de cliente para una API mTLS
Este es el escenario. Un socio de pagos, partner-api.acmebank.com, te emitió un certificado de cliente y una clave privada durante la incorporación. Su API es solo HTTPS y rechaza cualquier cliente que no pueda presentar ese certificado. Quieres llamar a GET /v1/settlements e inspeccionar la respuesta.
Paso 1: Abre la configuración de Certificados
Abre la configuración de Apidog usando el icono de configuración en la parte superior derecha, luego ve a la pestaña Certificados. Aquí es donde residen ambos tipos de certificados. Nada de lo que hay aquí está vinculado a una sola solicitud; se aplica a tus solicitudes basándose en la coincidencia del host.
Paso 2: Añade el certificado de cliente
En Certificados de Cliente, selecciona Añadir Certificado. Se abre un formulario para la vinculación del host y los archivos de certificado.
Rellena el campo Host solo con el dominio, sin protocolo:
partner-api.acmebank.com
Deja de lado https://. El campo acepta un dominio simple. Si necesitas un certificado para cubrir varios subdominios, el campo de host admite la coincidencia de patrones. Introducir *.acmebank.com utiliza el mismo certificado de cliente para cada subdominio de acmebank.com, lo cual es útil cuando un socio ejecuta partner-api, sandbox-api y settlements-api con el mismo certificado emitido.
El puerto personalizado es opcional. Déjalo en blanco y Apidog usará el valor predeterminado 443, el puerto HTTPS estándar. Solo establece un puerto si el endpoint mTLS escucha en otro lugar, por ejemplo, 8443.
Paso 3: Selecciona los archivos de certificado
Apidog acepta dos formatos de archivo para un certificado de cliente. Elige el que te haya dado tu socio:
- Archivos CRT + Clave. Un archivo de certificado y un archivo de clave privada separados. Selecciona cada uno en su campo.
- Archivos PFX. Un único archivo empaquetado que contiene el certificado y la clave juntos.
Si el certificado se generó con una frase de contraseña, introdúcela en el campo frase de contraseña. Es opcional, así que déjalo en blanco si tu clave no está protegida con contraseña. Un paquete de incorporación típico de un banco se envía como un par .crt y .key, a veces con una frase de contraseña en la clave.
Paso 4: Guárdalo
Selecciona Añadir para guardar el certificado de cliente. Ahora aparece en tu lista, vinculado a partner-api.acmebank.com. A partir de este momento, no lo vuelves a tocar por cada solicitud.
Paso 5: Envía la solicitud autenticada
Crea una solicitud al host y envíala:
GET https://partner-api.acmebank.com/v1/settlements
Authorization: Bearer <tu_token_oauth>
Apidog coincide con el host, adjunta tu certificado de cliente durante el handshake TLS y completa la autenticación TLS mutua antes de que se envíe la solicitud. Si el socio también requiere OAuth, ese token de portador viaja en la solicitud como de costumbre. El certificado prueba la máquina; el token prueba al emisor. Una respuesta exitosa podría verse así:
{
"settlements": [
{
"id": "stl_88213",
"amount": 41200,
"currency": "USD",
"status": "cleared",
"settled_at": "2026-07-14T09:31:00Z"
}
],
"next_cursor": null
}
Ningún paso manual por solicitud hizo que esto sucediera. La coincidencia del host lo hizo.
Añadir un certificado CA para raíces internas o autofirmadas
Los certificados de cliente son solo la mitad de la historia. La otra mitad aparece cuando el propio certificado del servidor está firmado por una autoridad en la que tu máquina no confía, algo común con los servicios internos y los entornos de preparación que utilizan una CA raíz privada.
Cuando eso sucede, la solicitud falla con un mensaje como SSL Error: Self signed certificate antes de que mTLS siquiera tenga una oportunidad. La solución es entregarle a Apidog la CA para que confíe en esa raíz.
En la misma pestaña de Certificados, activa el interruptor junto a Certificados CA, luego selecciona tu archivo PEM. Los certificados CA usan el formato PEM, y un solo archivo PEM puede contener múltiples certificados CA, por lo que puedes agrupar una cadena completa de raíces e intermediarios internos en un solo archivo:
-----BEGIN CERTIFICATE-----
MIIDdzCCAl+gAwIBAgIEAgAAuTANBgkqhkiG9w0BAQUFADBaMQswCQYDVQQG...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIIEFTCCAv2gAwIBAgIQeM8V5x8B3QksZ4 b2VqkJTANBgkqhkiG9w0BAQ...
-----END CERTIFICATE-----
Una vez que la CA es de confianza, Apidog deja de rechazar los endpoints firmados por ella. Combina una CA de confianza con un certificado de cliente y podrás probar un servicio mTLS interno que utiliza una raíz privada de extremo a extremo: la CA te permite confiar en su servidor, y el certificado de cliente les permite confiar en ti.
Consejos avanzados y variaciones comunes
Algunas cosas ahorran tiempo una vez que has superado la configuración básica.
Cobertura de subdominios con un solo certificado. Si un socio emitió un certificado con alcance de comodín, configura el host a *.acmebank.com una vez en lugar de registrar partner-api, sandbox-api y el resto por separado. Una sola vinculación, todos los subdominios.
Puertos no estándar. A los gateways mTLS internos les encantan puertos como el 8443 o el 9443. El predeterminado es el 443, así que especifica el puerto personalizado siempre que el punto final escuche en otro lugar, o el host no coincidirá y no se enviará ningún certificado.
Los certificados no son editables después de añadirlos. No hay acción de edición. Para rotar un certificado renovado o corregir un error tipográfico en el host, elimina el existente con el icono de eliminar y añádelo de nuevo. Incluye eso en tu manual de rotación de certificados para que nadie busque un botón de edición que no existe.
Un certificado por dominio. No registres dos certificados de cliente para el mismo dominio. Cada vinculación es específica del dominio, y un duplicado crea ambigüedad sobre cuál debe presentar Apidog. Mantén uno por host.
Mantén los certificados y la autorización separados en tu mente. Esta es la mayor fuente de confusión. mTLS reside en la pestaña Certificados. Las claves API, los tokens de portador, OAuth y la autenticación Básica residen en la pestaña Autorización de una solicitud o carpeta, y las solicitudes heredan la autorización de su carpeta principal. La autorización se aplica en tres niveles: solicitudes individuales, todas las solicitudes en una carpeta y todas las solicitudes en una colección. Si un socio necesita tanto un certificado de cliente como OAuth, configuras el certificado en Certificados y el token en Autorización. No se superponen. Para una mirada más profunda a la configuración de la autenticación basada en tokens, la guía de autenticación de gateway API cubre el lado de la solicitud, y si estás tratando con una pila pesada de Windows, la configuración de la autenticación Kerberos en Apidog es un tutorial hermano que vale la pena guardar.
Solo HTTPS, siempre. Apidog no adjuntará un certificado de cliente a una solicitud HTTP simple. Si tu objetivo de prueba es http://, el certificado nunca se envía y la lógica de handshake nunca se ejecuta. El endpoint debe ser HTTPS para que esto se aplique.
Automatiza el flujo de trabajo con la CLI de Apidog
Una vez que tus solicitudes mTLS pasen manualmente, incorpóralas a escenarios de prueba guardados y ejecútalas sin interfaz gráfica con la CLI de Apidog. Instálala y autentícate:
npm install -g apidog-cli
apidog login --with-token <TU_TOKEN_DE_ACCESO>
Luego, ejecuta un escenario guardado en un entorno:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t <id_escenario> -e <id_entorno> -r cli
El comando apidog run admite la configuración de certificados de cliente directamente, por lo que mTLS sobrevive al salto de la GUI a la pipeline. Para un solo certificado, pasa --ssl-client-cert (el certificado PEM), --ssl-client-key (la clave privada) y --ssl-client-passphrase si la clave tiene una. Apunta --ssl-extra-ca-certs a CA adicionales de confianza, o usa --ssl-client-cert-list con un archivo de configuración cuando coincidas certificados con hosts por patrón de URL. Los reporteros se configuran con -r (prueba -r html,cli). Conecta ese comando a un trabajo y tu API protegida con certificado se probará en cada push. La guía de CLI de Apidog en CI/CD cubre cómo ejecutarla dentro de una pipeline.
Preguntas frecuentes
¿Necesito un certificado de cliente y un certificado CA, o solo uno?
Depende del endpoint. Un certificado de cliente prueba tu identidad, por lo que lo necesitas siempre que el servidor exija TLS mutuo. Un certificado CA solo es necesario cuando el propio certificado del servidor está firmado por una autoridad en la que tu máquina aún no confía, como una CA raíz interna. Una API pública de un socio en una CA pública de confianza solo necesita el certificado de cliente; un servicio mTLS interno en una raíz privada suele necesitar ambos.
¿Por qué Apidog no envía mi certificado de cliente?
Casi siempre es una falta de coincidencia de host o un objetivo HTTP simple. Verifica que el campo Host contenga el dominio exacto sin el prefijo https://, que el puerto coincida (por defecto 443, así que establece un puerto personalizado si el endpoint escucha en otro lugar), y que la URL de la solicitud sea HTTPS. Apidog nunca adjunta un certificado a una solicitud HTTP.
¿Dónde van las claves API y los tokens de portador si no están en Certificados?
En la pestaña Autorización de la solicitud o carpeta, que es independiente de la configuración del certificado. Los certificados manejan la identidad de la capa TLS; la Autorización maneja la clave API, el token de portador, OAuth y la autenticación Básica en la capa de solicitud. Puedes encontrar el desglose completo de los tipos de autenticación en la guía de esquemas de seguridad, y puedes configurar la autenticación una vez a nivel de carpeta o colección para que cada solicitud la herede.
¿Puede un certificado cubrir varios subdominios?
Sí. El campo de host admite la coincidencia de patrones. Introduce *.example.com y el mismo certificado de cliente se aplica a todos los subdominios de example.com. Esa es la forma limpia de reutilizar un certificado con alcance de comodín que un socio emitió para varios de sus subdominios de API.
¿Cómo actualizo un certificado después de añadirlo?
Los certificados no son editables in situ. Elimina el existente con el icono de eliminar y luego añade la versión corregida o renovada. Tenlo en cuenta para la rotación de certificados, y mientras organizas las configuraciones de prueba, establecer parámetros globales en Apidog combina bien para mantener los valores del entorno ordenados en todas las solicitudes.
Conclusión
Probar una API protegida con mTLS se reduce a tres acciones en Apidog: vincular un certificado de cliente al host correcto, adjuntar un certificado CA si el servidor utiliza una raíz privada y dejar que la coincidencia de host firme automáticamente cada solicitud HTTPS. Mantén los certificados y la autorización en sus carriles separados y el handshake dejará de ser un misterio.
Descarga Apidog para seguir los pasos, añadir el certificado de tu socio y enviar esa primera solicitud autenticada. Pruébalo gratis, no se requiere tarjeta de crédito.