Points de terminaison IA API en marque blanche : domaines personnalisés, automatisation TLS et routage sécurisé par les locataires

Un client CNAME pointant vers votre passerelle ne crée pas de point de terminaison de marque prêt pour la production. L'enregistrement DNS peut être résolu avant qu'un certificat ne soit disponible, le certificat peut être renouvelé uniquement tant que les enregistrements de validation restent intacts, et un en-tête Host non coché peut acheminer une requête vers le mauvais contexte de locataire.

Le modèle le plus sûr consiste à traiter chaque nom d'hôte de marque comme une ressource de plan de contrôle durable. La propriété, l'émission de certificats, le basculement DNS, l'activation du routage, la suspension et la suppression nécessitent chacun un état explicite. Au moment de la requête, le nom d'hôte restreint le contexte de locataire autorisé, tandis que la clé API reste la limite d'autorisation.

Séparez le cycle de vie du domaine en vérifications indépendantes

Ne représentez pas un domaine personnalisé avec un seul booléen tel que verified. Au minimum, suivez quatre conditions indépendantes :

• Propriété : Le client a-t-il prouvé qu'il contrôle le nom d'hôte ?
• Certificat : Un certificat valide a-t-il été émis et déployé à la périphérie ?
• DNS : Le DNS faisant autorité pointe-t-il vers le DNS attendu ? cible de la passerelle ?
• Routage : Le nom d'hôte exact est-il lié à un locataire actif et à un profil de routage ?

Cette séparation reflète le comportement documenté du fournisseur Edge. Les produits gérés avec nom d'hôte personnalisé peuvent utiliser différents enregistrements et statuts pour la propriété du nom d'hôte et la validation des certificats. La résolution DNS à elle seule ne prouve donc pas que le point de terminaison est prêt.

Une machine à états pratique est :

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

Il s'agit d'états métier, et non de copies directes des statuts des fournisseurs. Stockez le statut brut du fournisseur séparément, puis dérivez votre propre état en fonction des invariants documentés. Par exemple, marquez un domaine ready uniquement lorsque la propriété est valide, que le certificat est actif, que le DNS pointe vers la cible attendue et que la route périphérique est activée.

Recommandation : effectuez des transitions monotones lors de l'activation initiale. Une sonde TLS réussie et transitoire ne doit pas ignorer la validation de propriété ou les vérifications de routage. Après l'activation, la réconciliation peut déplacer un domaine de ready à suspended ou un état explicitement dégradé lorsque ces invariants cessent de fonctionner.

Stocker un domaine en tant que ressource de première classe

Un enregistrement de domaine pour une passerelle d'IA en marque blanche opérationnelle API doit contenir suffisamment d'informations pour récupérer des API appels et fournisseurs ambigus drift :

{
  "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"
}

Normalisez le nom d'hôte en ASCII minuscule à l'aide d'une bibliothèque compatible IDNA avant les vérifications d'unicité. Supprimez un point final et rejetez les littéraux IP, les chemins d'URL, les ports, les caractères génériques sauf s'ils sont explicitement pris en charge, ainsi que les noms en dehors de votre politique de suffixe public acceptée. Conservez le formulaire d'affichage soumis uniquement en tant que métadonnées ne faisant pas autorité.

Appliquer une contrainte d'unicité globale sur le nom d'hôte normalisé. Deux locataires ne doivent jamais pouvoir revendiquer la même autorité, même lorsqu'ils utilisent des majuscules ou des représentations Unicode différentes.

Prévalidez avant de modifier le DNS de production

Lorsque la plate-forme Edge le prend en charge, émettez et déployez le certificat avant de demander au client de modifier le CNAME de production.Une séquence typique est la suivante :

1. Créez la ressource de domaine avec une clé d'idempotence.
2. Renvoyer les enregistrements de propriété et de validation du certificat.
3. Interroger ou recevoir les événements du fournisseur jusqu'à ce que les deux validations réussissent.
4. Confirmez que le certificat est déployé pour le nom d'hôte exact.
5. Demandez au client de pointer le CNAME de production vers la passerelle. target.
6. Résolvez les DNS faisant autorité à partir de plusieurs emplacements réseau.
7. Activez la route et effectuez une sonde authentifiée de bout en bout.
8. Marquez le domaine ready.

Fait : La documentation SaaS-Edge gérée décrit les séquences de migration sans temps d'arrêt dans lesquelles la validation et l'émission du certificat a lieu avant les modifications du CNAME de production. Compromis : cela évite un écart d'activation TLS visible, mais oblige le client à créer des enregistrements TXT, CNAME ou de validation délégués supplémentaires.

Si la prévalidation n'est pas disponible, exposez explicitement l'interruption probable. Ne promettez pas de temps d'arrêt nul lorsque l'émission du certificat commence seulement après le déplacement du trafic.

Acheminez par autorité exacte, puis autorisez la clé

Le dispositif Edge approuvé doit maintenir une liste blanche exacte allant du nom d'hôte au contexte de locataire ou de marque autorisé :

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

Rejeter les autorités inconnues, inactives et ambiguës. Ne les envoyez jamais à un locataire par défaut. Pour HTTP/1.1, validez Host ; pour HTTP/2 et HTTP/3, validez :authority. Lorsque TLS se termine au même niveau de périphérie, comparez l'autorité de requête avec le contexte SNI et de certificat pris en charge par le proxy.

Les en-têtes de transfert nécessitent la même discipline. Le dispositif Edge public doit supprimer les en-têtes X-Forwarded-Host, Forwarded entrants et tous les en-têtes de locataire internes, puis ajouter un hôte canonique et un signal de locataire résolu. L'origine doit accepter ces signaux uniquement via des connexions Edge-to-Origin authentifiées.

La séquence d'autorisation d'exécution doit être :

1. Résoudre l'autorité normalisée via la liste d'autorisation de nom d'hôte active.
2. Authentifier la clé API indépendamment.
3. Charger l'identifiant de locataire immuable attaché au key.
4. Vérifiez que le locataire de la clé est autorisé sur le nom d'hôte résolu.
5. Appliquez le modèle, le budget, la limite de débit et la stratégie de routage à l'aide des ID de locataire et de clé.
6. Écrivez des enregistrements d'utilisation sur ces ID immuables, et non sur le nom d'hôte.

Cela préserve le rôle de Partenaire API automatisation sans transformer une opération de gestion de domaine en raccourci d'autorisation.

Renvoyer 421 Misdirected Request lorsque l'autorité ne correspond pas à l'origine ou au contexte de connexion configuré. Renvoie 403 Forbidden lorsque le nom d'hôte est valide mais que la clé authentifiée appartient à un locataire qui n'est pas autorisé à l'utiliser. Gardez les corps d'erreur suffisamment génériques pour qu'ils ne révèlent pas quel locataire possède un nom d'hôte.

Compatibilité canonique et avec les points de terminaison de marque

Certains clients ont besoin d'une seule clé pour travailler à la fois sur le point de terminaison canonique de la passerelle et sur leur point de terminaison de marque. Cela n’est acceptable que lorsque les deux noms d’hôte correspondent au même contexte de locataire autorisé.La liaison stricte de chaque clé à un nom d'hôte réduit l'utilisation entre marques, mais complique les migrations et les clients qui basculent entre les points de terminaison.

Recommandation : le modèle autorisait les contextes de point de terminaison en tant que stratégie de clé plutôt que de comparer les chaînes dans le code de l'application. Par exemple, une clé peut autoriser tenant:any-active-hostname, brand:brand_42 ou un domain_id exact.

Exposer les opérations de cycle de vie via le partenaire API

Un minimum API doit prendre en charge la création, l'inspection, la revalidation, la suspension, la reprise et la suppression :

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}

Les opérations de création et de suppression doivent accepter des clés d'idempotence stables. Les API du fournisseur, la propagation DNS et les délais d'attente du réseau peuvent laisser l'appelant dans l'incertitude quant à la réussite d'une opération. Conservez l'enregistrement de l'opération avant d'appeler le fournisseur Edge et renvoyez le même domaine ou la même opération de suppression lorsque la demande est réessayée avec la même clé et la même charge utile équivalente.

Émet des événements de cycle de vie signés tels que custom_domain.verification_required, custom_domain.certificate_active, custom_domain.ready, custom_domain.dns_drifted, custom_domain.renewal_at_risk et custom_domain.deleted. Les événements sont des notifications, et non la seule source de vérité ; les consommateurs devraient pouvoir récupérer l'état actuel après une livraison manquée ou dupliquée.

Réconcilier le DNS, les certificats et le routage en continu

L'activation n'est pas la fin du cycle de vie. Les enregistrements DNS sont modifiés, les enregistrements de validation disparaissent, les dérives de configuration Edge et le renouvellement des certificats approche.

Exécutez un rapprocheur périodique qui vérifie :

• Le DNS faisant autorité et le CNAME ou la cible déléguée attendue
• Le nom d'hôte du fournisseur et l'état des certificats
• Noms, expiration et renouvellement des certificats health
• Présence des enregistrements de validation DNS requis
• Propriété exacte de la route périphérique et état d'activation
• L'éligibilité actuelle du locataire à desservir le trafic

L'automatisation des certificats validés par DNS peut dépendre de la validation des enregistrements CNAME qui restent publiquement résolus. Alerter avant l'expiration au lieu de supposer que le renouvellement automatique réussira toujours.

Utilisez des tentatives limitées avec un délai d'attente exponentiel et une instabilité pour les opérations de certificat. Préservez le compte ACME et l’état de la commande où vous effectuez directement l’émission. Les suppressions et recréations répétées peuvent consommer les limites de débit des commandes de certificats ou des domaines enregistrés. Les enregistrements de nom d'hôte en attente peuvent également consommer le quota du fournisseur jusqu'à ce qu'ils soient explicitement supprimés.

Prédiction opérationnelle : sans réconciliation, les échecs les plus courants apparaîtront après une intégration réussie, lors de modifications DNS, de renouvellement de certificat, de dérive côté fournisseur ou de désabonnement des clients. Il s'agit d'une attente architecturale, et non d'un taux d'échec mesuré.

Désintégration en deux phases

La suppression préalable de la ligne de base de données n'est pas sûre, car les mappages périphériques, les certificats ou le DNS peuvent lui survivre.Utilisez un flux de travail en deux phases auditable :

1. Déplacez le domaine vers draining et arrêtez de le publier pour de nouvelles intégrations.
2. Décidez si les requêtes existantes bénéficient d'un court délai de grâce ou d'un rejet immédiat.
3. Désactivez la route périphérique afin que le nom d'hôte ne puisse pas être résolu en locataire par défaut.
4. Supprimez l'association de nom d'hôte personnalisé et de certificat du fournisseur.
5. Demandez au client de supprimer ou de remplacer l'enregistrement DNS.
6. Vérifiez que le DNS ne pointe plus vers votre service.
7. Marquez la ressource deleted tout en conservant les identifiants et un enregistrement d'audit.

Un CNAME en suspens qui cible un service déprovisionné peut créer un risque de prise de contrôle de sous-domaine. À l’inverse, laisser un mappage obsolète actif peut continuer à envoyer le trafic d’un ancien client via votre périphérie. Associez le nettoyage du fournisseur et la vérification DNS à la même opération de suppression, mais enregistrez chaque résultat indépendamment.

Testez la limite, pas seulement le chemin heureux

Avant d'activer les domaines clients, automatisez les tests de conformité pour :

• Un en-tête Host ou X-Forwarded-Host falsifié
• SNI et HTTP en conflit valeurs d'autorité
• Un nom d'hôte inconnu et un nom d'hôte connu mais suspendu
• Une clé valide du locataire A utilisée sur le nom d'hôte du locataire B
• Demandes de création et de suppression en double avec la même clé d'idempotence
• Le même nom d'hôte soumis avec des variations de casse, de point final ou d'Unicode
• Le DNS a changé par rapport à la cible attendue après l'activation
• Un enregistrement de validation de certificat supprimé avant le renouvellement
• Suppression interrompue après la suppression du mappage périphérique mais avant les modifications DNS

Vérifiez également que les journaux, la facturation, l'attribution d'utilisation, les limites de débit et les décisions politiques utilisent les identifiants de locataire et de clé. Les noms d'hôtes sont des entrées de présentation et de routage mutables ; ils ne doivent pas devenir des identités financières ou de sécurité.

Liste de contrôle de mise en œuvre

• Normaliser les noms d'hôtes et appliquer l'unicité globale.
• Suivez séparément la propriété, le certificat, le DNS et l'état de préparation du routage.
• Prévalidez les certificats avant le basculement lorsque cela est pris en charge.
• Autoriser les autorités exactes au niveau du site. Trust Edge.
• Supprimez les en-têtes de transfert non fiables et créez un signal d'origine authentifié.
• Autorisez la clé API par rapport au contexte du locataire du nom d'hôte.
• Utilisez 421 pour une incompatibilité d'origine ou de connexion et 403 pour une utilisation de clé entre locataires.
• Créez la création et la suppression idempotent.
• Réconciliez continuellement l'état du fournisseur, le DNS, le routage et le renouvellement.
• Supprimez explicitement les mappages de périphérie et vérifiez le DNS lors de la désintégration.

Un point de terminaison de marque n'est prêt que lorsque l'état du plan de contrôle et le comportement du plan de données sont d'accord.Modélisez explicitement cet accord, testez les chemins négatifs et conservez la clé API comme limite d'autorisation finale du locataire.

Lecture connexe

• Partenaire idempotent API opérations