Puntos finales API de IA de marca blanca: dominios personalizados, automatización TLS y enrutamiento seguro para inquilinos

Un CNAME de cliente que apunte a su puerta de enlace no crea un punto final de marca listo para producción. El registro DNS puede resolverse antes de que un certificado esté disponible, el certificado puede renovarse solo mientras los registros de validación permanecen intactos y un encabezado Host sin marcar puede enrutar una solicitud al contexto de inquilino incorrecto.

El modelo más seguro es tratar cada nombre de host de marca como un recurso duradero del plano de control. La propiedad, la emisión de certificados, la transferencia de DNS, la activación de enrutamiento, la suspensión y la eliminación necesitan un estado explícito. En el momento de la solicitud, el nombre de host reduce el contexto de inquilino permitido, mientras que la clave API sigue siendo el límite de autorización.

Separe el ciclo de vida del dominio en comprobaciones independientes

No represente un dominio personalizado con un único booleano como verified. Como mínimo, realice un seguimiento de cuatro condiciones independientes:

• Propiedad: ¿El cliente ha demostrado control del nombre de host?
• Certificado: ¿Se ha emitido e implementado un certificado válido en el borde?
• DNS: ¿El DNS autorizado apunta al servidor esperado? ¿Destino de puerta de enlace?
• Enrutamiento: ¿El nombre de host exacto está vinculado a un inquilino activo y a un perfil de enrutamiento?

Esta separación refleja el comportamiento documentado del proveedor perimetral. Los productos administrados con nombres de host personalizados pueden usar diferentes registros y estados para la propiedad del nombre de host y la validación de certificados. Por lo tanto, la resolución de DNS por sí sola no prueba que el punto final esté listo.

Una máquina de estado práctica es:

requested
  -> ownership_pending
  -> certificate_pending
  -> dns_pending
  -> ready
  -> suspended
  -> draining
  -> deleted

Estos son estados comerciales, no copias directas de los estados del proveedor. Almacene el estado sin procesar del proveedor por separado y luego obtenga su propio estado de acuerdo con las invariantes documentadas. Por ejemplo, marque un dominio ready solo cuando la propiedad sea válida, el certificado esté activo, DNS apunte al destino esperado y la ruta perimetral esté habilitada.

Recomendación: haga que las transiciones sean monótonas durante la activación inicial. Una sonda TLS transitoria exitosa no debe omitir la validación de propiedad ni las comprobaciones de enrutamiento. Después de la activación, la reconciliación puede mover un dominio de ready a suspended o un estado degradado explícito cuando esas invariantes dejan de mantenerse.

Almacenar un dominio como un recurso de primera clase

Un registro de dominio para una puerta de enlace operativa API de IA de marca blanca debe contener suficiente información para recuperarse de API llamadas y proveedores ambiguos. deriva:

{
  "domain_id": "dom_01J...",
  "hostname_ascii": "api.customer.example",
  "tenant_id": "ten_01H...",
  "brand_id": "brand_42",
  "state": "certificate_pending",
  "ownership_method": "dns_txt",
  "ownership_record": {
    "name": "_gateway-verify.api.customer.example",
    "value": "verify=..."
  },
  "certificate_status": "pending_validation",
  "expected_cname": "customers.edge.example",
  "routing_profile_id": "route_openai_compatible_v3",
  "provider_hostname_id": "edge_8f2...",
  "creation_operation_id": "op_01J...",
  "last_reconciled_at": "2026-11-02T10:00:00Z",
  "last_reconciliation_result": "certificate_pending"
}

Normalice el nombre de host a ASCII en minúsculas utilizando una biblioteca compatible con IDNA antes de realizar comprobaciones de unicidad. Elimine un punto final y rechace literales de IP, rutas de URL, puertos, comodines a menos que se admitan explícitamente y nombres fuera de su política de sufijos públicos aceptados. Conserve el formulario de visualización enviado solo como metadatos no autorizados.

Aplicar una restricción de unicidad global en el nombre de host normalizado. Dos inquilinos nunca deben poder reclamar la misma autoridad, incluso cuando usan diferentes mayúsculas o representaciones Unicode.

Validar previamente antes de cambiar el DNS de producción

Cuando la plataforma perimetral lo admita, emita e implemente el certificado antes de pedirle al cliente que cambie el CNAME de producción.Una secuencia típica es:

1. Crear el recurso de dominio con una clave de idempotencia.
2. Devolver los registros de propiedad y de validación del certificado.
3. Sondear o recibir eventos del proveedor hasta que ambas validaciones sean exitosas.
4. Confirmar que el certificado esté implementado para el nombre de host exacto.
5. Pida al cliente que apunte el CNAME de producción a la puerta de enlace target.
6. Resolver DNS autorizado desde más de una ubicación de red.
7. Habilite la ruta y realice un sondeo autenticado de un extremo a otro.
8. Marque el dominio ready.

Hecho: la documentación de SaaS administrada en el borde describe secuencias de migración sin tiempo de inactividad en las que se realiza la validación y la emisión del certificado se produce antes de que cambie el CNAME de producción. Compensación: esto evita una brecha visible en la activación de TLS, pero requiere que el cliente cree TXT, CNAME o registros de validación delegados adicionales.

Si la prevalidación no está disponible, exponga explícitamente la posible interrupción. No prometa tiempo de inactividad cero cuando la emisión de certificados comience solo después de que el tráfico se haya movido.

Enrute según la autoridad exacta y luego autorice la clave

El borde confiable debe mantener una lista de permitidos exacta desde el nombre de host hasta el inquilino permitido o el contexto de marca:

api.customer.example -> {
  tenant_id: "ten_01H...",
  brand_id: "brand_42",
  state: "ready"
}

Rechace autoridades desconocidas, inactivas y ambiguas. Nunca los envíe a un inquilino predeterminado. Para HTTP/1.1, valide Host; para HTTP/2 y HTTP/3, valide :authority. Cuando TLS termina en el mismo borde, compare la autoridad de solicitud con el SNI y el contexto del certificado admitido por el proxy.

El reenvío de encabezados requiere la misma disciplina. El borde público debe eliminar los números entrantes X-Forwarded-Host, Forwarded y cualquier encabezado de inquilino interno, luego agregar un host canónico y una señal de inquilino resuelta. El origen debe aceptar esas señales solo a través de conexiones autenticadas de borde a origen.

La secuencia de autorización en tiempo de ejecución debe ser:

1. Resolver la autoridad normalizada a través de la lista permitida de nombres de host activos.
2. Autenticar la clave API de forma independiente.
3. Cargar el identificador de inquilino inmutable adjunto al clave.
4. Verifique que el inquilino de la clave esté permitido en el nombre de host resuelto.
5. Aplicar modelo, presupuesto, límite de velocidad y política de enrutamiento utilizando los ID de inquilino y clave.
6. Escribir registros de uso en esos ID inmutables, no en el nombre de host.

Esto preserva el rol de Socio API automatización sin convertir una operación de administración de dominio en un acceso directo de autorización.

Devuelve 421 Misdirected Request cuando la autoridad no coincide con el origen configurado o el contexto de conexión. Devuelve 403 Forbidden cuando el nombre de host es válido pero la clave autenticada pertenece a un inquilino que no tiene permiso para usarla. Mantenga los cuerpos de error lo suficientemente genéricos como para no revelar qué inquilino posee un nombre de host.

Compatibilidad con terminales canónicos y de marca

Algunos clientes necesitan una clave para funcionar tanto en el extremo canónico de la puerta de enlace como en su punto final de marca. Esto sólo es aceptable cuando ambos nombres de host se resuelven en el mismo contexto de inquilino autorizado.Vincular estrictamente cada clave a un nombre de host reduce el uso entre marcas, pero complica las migraciones y los clientes que cambian entre puntos finales.

Recomendación: el modelo permitía contextos de puntos finales como política de claves en lugar de comparar cadenas dentro del código de la aplicación. Por ejemplo, una clave puede permitir tenant:any-active-hostname, brand:brand_42 o un domain_id exacto.

Exponer operaciones del ciclo de vida a través del socio API

Un mínimo API debe admitir la creación, inspección, revalidación, suspensión, reanudación y eliminación:

POST   /partner/v1/custom-domains
GET    /partner/v1/custom-domains/{domain_id}
POST   /partner/v1/custom-domains/{domain_id}/revalidate
POST   /partner/v1/custom-domains/{domain_id}/suspend
POST   /partner/v1/custom-domains/{domain_id}/resume
DELETE /partner/v1/custom-domains/{domain_id}

Las operaciones de creación y eliminación deben aceptar claves de idempotencia estables. Las API del proveedor, la propagación de DNS y los tiempos de espera de la red pueden hacer que la persona que llama no esté segura de si una operación se realizó correctamente. Conserve el registro de operación antes de invocar al proveedor perimetral y devuelva el mismo dominio u operación de eliminación cuando se reintente la solicitud con la misma clave y carga útil equivalente.

Emitir eventos de ciclo de vida firmados como custom_domain.verification_required, custom_domain.certificate_active, custom_domain.ready, custom_domain.dns_drifted, custom_domain.renewal_at_risk y custom_domain.deleted. Los eventos son notificaciones, no la única fuente de verdad; los consumidores deberían poder recuperar el estado actual después de una entrega perdida o duplicada.

Conciliar DNS, certificados y enrutamiento continuamente

La activación no es el final del ciclo de vida. Los registros DNS se editan, los registros de validación desaparecen, la configuración perimetral cambia y los certificados se acercan a la renovación.

Ejecute un reconciliador periódico que verifica:

• DNS autorizado y el CNAME esperado o el destino delegado
• Nombre de host del proveedor y estados de los certificados
• Nombres, caducidad y renovación de los certificados salud
• Presencia de registros de validación DNS requeridos
• Propiedad exacta de la ruta perimetral y estado de activación
• La elegibilidad actual del inquilino para atender el tráfico

La automatización de certificados validados por DNS puede depender de que los registros CNAME de validación sigan siendo resolubles públicamente. Alerta antes de la caducidad en lugar de asumir que la renovación automática siempre se realizará correctamente.

Utilice reintentos limitados con retroceso exponencial y fluctuación para las operaciones de certificados. Conserve la cuenta ACME y el estado del pedido donde opera la emisión directamente. La eliminación y recreación repetidas pueden consumir los límites de tasa de orden de certificado o dominio registrado. Los registros de nombres de host pendientes también pueden consumir la cuota del proveedor hasta que se eliminen explícitamente.

Predicción operativa: sin conciliación, los errores más comunes aparecerán después de una incorporación exitosa, durante las ediciones de DNS, la renovación de certificados, la deriva del lado del proveedor o la rotación de clientes. Esta es una expectativa arquitectónica, no una tasa de falla medida.

Desactivación en dos fases

Eliminar primero la fila de la base de datos no es seguro porque las asignaciones de borde, los certificados o el DNS pueden sobrevivir.Utilice un flujo de trabajo de dos fases auditable:

1. Mueva el dominio a draining y deje de anunciarlo para nuevas integraciones.
2. Decida si las solicitudes existentes reciben un breve período de gracia o un rechazo inmediato.
3. Deshabilite la ruta perimetral para que el nombre de host no pueda resolverse en un inquilino predeterminado.
4. Elimine el nombre de host personalizado y la asociación de certificado del proveedor.
5. Solicite al cliente que elimine o reemplace el registro DNS.
6. Verifique que DNS ya no apunte a su servicio.
7. Marque el recurso deleted conservando identificadores y un registro de auditoría.

Un CNAME pendiente dirigido a un servicio dado de baja puede crear un riesgo de adquisición de subdominio. Por el contrario, dejar activo un mapeo obsoleto puede continuar enviando el tráfico de un antiguo cliente a través de su borde. Combine la limpieza del proveedor y la verificación de DNS en la misma operación de eliminación, pero registre cada resultado de forma independiente.

Pruebe los límites, no solo el camino feliz

Antes de habilitar los dominios de los clientes, automatice las pruebas de conformidad para:

• Un encabezado Host o X-Forwarded-Host falsificado
• SNI y autoridad HTTP en conflicto valores
• Un nombre de host desconocido y un nombre de host conocido pero suspendido
• Una clave válida del inquilino A utilizada en el nombre de host del inquilino B
• Solicitudes de creación y eliminación duplicadas con la misma clave de idempotencia
• El mismo nombre de host enviado con variaciones de mayúsculas y minúsculas, puntos finales o Unicode
• DNS cambiado fuera del objetivo esperado después de la activación
• Un registro de validación de certificado eliminado antes de la renovación
• La eliminación se interrumpe después de que se elimina la asignación de borde pero antes de los cambios de DNS

Verifique también que los registros, la facturación, la atribución de uso, los límites de tarifas y las decisiones de políticas utilicen ID de clave y inquilino. Los nombres de host son entradas de presentación y enrutamiento mutables; no deben convertirse en identidades financieras o de seguridad.

Lista de verificación de implementación

• Normalizar los nombres de host y aplicar la unicidad global.
• Seguir la propiedad, el certificado, el DNS y la preparación de la ruta por separado.
• Validar previamente los certificados antes de la transición cuando sea compatible.
• Enumerar las autoridades exactas permitidas en el borde confiable.
• Elimine los encabezados de reenvío que no sean de confianza y cree una señal de origen autenticada.
• Autorice la clave API en el contexto del inquilino del nombre de host.
• Utilice 421 para el origen o la conexión y la 403 para el uso de la clave entre inquilinos.
• Crear y eliminar idempotent.
• Concilie el estado del proveedor, el DNS, el enrutamiento y el estado de renovación continuamente.
• Elimine las asignaciones de borde explícitamente y verifique el DNS durante la salida.

Un punto final de marca está listo solo cuando el estado del plano de control y el comportamiento del plano de datos coinciden.Modele ese acuerdo explícitamente, pruebe las rutas negativas y mantenga la clave API como límite final de autorización del inquilino.

Lectura relacionada

• Operaciones de socio idempotente API