White-Label-KI API-Endpunkte: Benutzerdefinierte Domänen, TLS-Automatisierung und mandantensicheres Routing

Ein Kunden-CNAME, der auf Ihr Gateway verweist, erstellt keinen produktionsbereiten Markenendpunkt. Der DNS-Eintrag wird möglicherweise aufgelöst, bevor ein Zertifikat verfügbar ist, das Zertifikat kann nur erneuert werden, während die Validierungsdatensätze intakt bleiben, und ein ungeprüfter Host-Header kann eine Anfrage in den falschen Mandantenkontext weiterleiten.

Das sicherere Modell besteht darin, jeden gebrandeten Hostnamen als dauerhafte Ressource auf der Steuerungsebene zu behandeln. Besitz, Zertifikatsausstellung, DNS-Umstellung, Routing-Aktivierung, Aussetzung und Löschung erfordern jeweils einen expliziten Status. Zum Zeitpunkt der Anforderung schränkt der Hostname den zulässigen Mandantenkontext ein, während der Schlüssel API die Autorisierungsgrenze bleibt.

Teilen Sie den Domänenlebenszyklus in unabhängige Prüfungen auf.

Stellen Sie keine benutzerdefinierte Domäne mit einem einzelnen Booleschen Wert wie verified dar. Verfolgen Sie mindestens vier unabhängige Bedingungen:

• Eigentum: Hat der Kunde die Kontrolle über den Hostnamen nachgewiesen?
• Zertifikat: Wurde ein gültiges Zertifikat ausgestellt und am Edge bereitgestellt?
• DNS: Zeigt autorisierendes DNS auf das erwartete Gateway Ziel?
• Routing: Ist der genaue Hostname an einen aktiven Mandanten und ein Routing-Profil gebunden?

Diese Trennung spiegelt das dokumentierte Edge-Provider-Verhalten wider. Verwaltete benutzerdefinierte Hostnamenprodukte können unterschiedliche Datensätze und Status für Hostnamenbesitz und Zertifikatsvalidierung verwenden. Die DNS-Auflösung allein beweist daher nicht, dass der Endpunkt bereit ist.

Eine praktische Zustandsmaschine ist:

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

Dies sind Geschäftszustände, keine direkten Kopien der Anbieterstatus. Speichern Sie den Rohstatus des Anbieters separat und leiten Sie dann Ihren eigenen Status anhand dokumentierter Invarianten ab. Markieren Sie beispielsweise eine Domäne ready nur, wenn der Besitz gültig ist, das Zertifikat aktiv ist, DNS auf das erwartete Ziel verweist und die Edge-Route aktiviert ist.

Empfehlung: Machen Sie die Übergänge bei der Erstaktivierung monoton. Eine vorübergehend erfolgreiche TLS-Prüfung sollte die Besitzvalidierung oder Routing-Prüfungen nicht überspringen. Nach der Aktivierung kann der Abgleich eine Domäne von ready nach suspended oder in einen expliziten herabgesetzten Zustand verschieben, wenn diese Invarianten nicht mehr gültig sind.

Speichern Sie eine Domäne als erstklassige Ressource.

Ein Domänendatensatz für ein betriebsfähiges White-Label-KI-Gateway API sollte genügend Informationen enthalten, um eine Wiederherstellung nach mehrdeutigen API Aufrufen und Anbietern zu ermöglichen 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"
}

Normalisieren Sie den Hostnamen mithilfe einer IDNA-fähigen Bibliothek vor der Eindeutigkeitsprüfung auf ASCII-Kleinbuchstaben. Entfernen Sie einen abschließenden Punkt und lehnen Sie IP-Literale, URL-Pfade, Ports, Platzhalter (sofern nicht ausdrücklich unterstützt) und Namen außerhalb Ihrer akzeptierten Richtlinie für öffentliche Suffixe ab. Behalten Sie das übermittelte Anzeigeformular nur als nicht autorisierende Metadaten bei.

Erzwingen Sie eine globale Eindeutigkeitsbeschränkung für den normalisierten Hostnamen. Zwei Mandanten dürfen niemals die gleiche Autorität beanspruchen können, auch wenn sie unterschiedliche Groß- und Kleinschreibung oder Unicode-Darstellungen verwenden.

Vorab validieren, bevor Produktions-DNS geändert wird

Wenn die Edge-Plattform dies unterstützt, stellen Sie das Zertifikat aus und stellen Sie es bereit, bevor Sie den Kunden auffordern, den Produktions-CNAME zu ändern.Eine typische Sequenz ist:

1. Erstellen Sie die Domänenressource mit einem Idempotenzschlüssel.
2. Geben Sie die Eigentums- und Zertifikatsvalidierungsdatensätze zurück.
3. Abfragen oder empfangen Sie Anbieterereignisse, bis beide Validierungen erfolgreich sind.
4. Bestätigen Sie, dass das Zertifikat für den genauen Hostnamen bereitgestellt wird.
5. Bitten Sie den Kunden, den Produktions-CNAME auf das Gateway zu verweisen target.
6. Autorisierendes DNS von mehr als einem Netzwerkstandort auflösen.
7. Die Route aktivieren und eine authentifizierte End-to-End-Prüfung durchführen.
8. Domäne markieren ready.

Fakt: Die verwaltete SaaS-Edge-Dokumentation beschreibt Migrationssequenzen ohne Ausfallzeiten, in denen Validierung und Zertifikatsausstellung erfolgen, bevor sich der Produktions-CNAME ändert. Kompromiss: Dies vermeidet eine sichtbare TLS-Aktivierungslücke, erfordert jedoch, dass der Kunde zusätzliche TXT-, CNAME- oder delegierte Validierungsdatensätze erstellt.

Wenn die Vorvalidierung nicht verfügbar ist, legen Sie die wahrscheinliche Unterbrechung explizit offen. Versprechen Sie keine Ausfallzeiten von Null, wenn die Zertifikatsausstellung erst beginnt, nachdem der Datenverkehr verschoben wurde.

Nach genauer Autorität weiterleiten und dann den Schlüssel autorisieren

Der vertrauenswürdige Edge sollte eine genaue Zulassungsliste vom Hostnamen bis zum zulässigen Mandanten- oder Markenkontext führen:

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

Unbekannte, inaktive und mehrdeutige Autoritäten ablehnen. Senden Sie sie niemals an einen Standardmieter. Validieren Sie für HTTP/1.1 Host; für HTTP/2 und HTTP/3 :authority validieren. Wenn TLS am selben Edge beendet wird, vergleichen Sie die Anforderungsautorität mit dem SNI- und Zertifikatskontext, der vom Proxy unterstützt wird.

Weiterleitungsheader erfordern die gleiche Disziplin. Der öffentliche Edge sollte eingehende X-Forwarded-Host, Forwarded und alle internen Mandanten-Header entfernen und dann einen kanonischen Host und ein aufgelöstes Mandantensignal hinzufügen. Der Ursprung sollte diese Signale nur über authentifizierte Edge-zu-Ursprung-Verbindungen akzeptieren.

Die Laufzeitautorisierungssequenz sollte sein:

1. Lösen Sie die normalisierte Autorität über die aktive Hostnamen-Zulassungsliste auf.
2. Authentifizieren Sie den API-Schlüssel unabhängig.
3. Laden Sie die angehängte unveränderliche Mandantenkennung Schlüssel.
4. Überprüfen Sie, ob der Mandant des Schlüssels auf dem aufgelösten Hostnamen zulässig ist.
5. Wenden Sie Modell, Budget, Ratenbegrenzung und Routing-Richtlinie mithilfe von Mandanten- und Schlüssel-IDs an.
6. Schreiben Sie Nutzungsdatensätze für diese unveränderlichen IDs, nicht für den Hostnamen.

Dadurch bleibt die Rolle von Partner API erhalten. Automatisierung, ohne einen Domänenverwaltungsvorgang in eine Autorisierungsverknüpfung umzuwandeln.

Gibt 421 Misdirected Request zurück, wenn die Autorität nicht mit dem konfigurierten Ursprungs- oder Verbindungskontext übereinstimmt. Geben Sie 403 Forbidden zurück, wenn der Hostname gültig ist, der authentifizierte Schlüssel jedoch zu einem Mandanten gehört, der ihn nicht verwenden darf. Halten Sie die Fehlerkörper generisch genug, damit sie nicht offenlegen, welcher Mandant einen Hostnamen besitzt.

Kompatibilität mit kanonischen und Markenendpunkten

Einige Kunden benötigen einen Schlüssel, um sowohl am kanonischen Endpunkt des Gateways als auch an ihrem Markenendpunkt zu arbeiten. Dies ist nur akzeptabel, wenn beide Hostnamen in denselben autorisierten Mandantenkontext aufgelöst werden.Die strikte Bindung jedes Schlüssels an einen Hostnamen reduziert die markenübergreifende Verwendung, erschwert jedoch Migrationen und Clients, die zwischen Endpunkten wechseln.

Empfehlung: Modellieren Sie zulässige Endpunktkontexte als Schlüsselrichtlinie, anstatt Zeichenfolgen innerhalb des Anwendungscodes zu vergleichen. Beispielsweise kann ein Schlüssel tenant:any-active-hostname, brand:brand_42 oder ein genaues domain_id zulassen.

Lebenszyklusvorgänge über den Partner verfügbar machen API

Ein minimaler API sollte das Erstellen, Überprüfen, erneute Validieren, Anhalten, Fortsetzen und Löschen unterstützen:

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}

Erstellungs- und Löschvorgänge sollten stabile Idempotenzschlüssel akzeptieren. Anbieter-APIs, DNS-Weitergabe und Netzwerk-Timeouts können dazu führen, dass der Aufrufer unsicher ist, ob ein Vorgang erfolgreich war. Behalten Sie den Vorgangsdatensatz bei, bevor Sie den Edge-Anbieter aufrufen, und geben Sie dieselbe Domäne oder denselben Löschvorgang zurück, wenn die Anforderung mit demselben Schlüssel und der gleichen Nutzlast erneut versucht wird.

Signierte Lebenszyklusereignisse wie custom_domain.verification_required, custom_domain.certificate_active, custom_domain.ready, custom_domain.dns_drifted, custom_domain.renewal_at_risk und custom_domain.deleted ausgeben. Ereignisse sind Benachrichtigungen, nicht die einzige Quelle der Wahrheit; Verbraucher sollten in der Lage sein, den aktuellen Status nach verpasster oder doppelter Zustellung abzurufen.

DNS, Zertifikate und Routing kontinuierlich abgleichen

Die Aktivierung ist nicht das Ende des Lebenszyklus. DNS-Einträge werden bearbeitet, Validierungseinträge verschwinden, Edge-Konfigurationsabweichungen und Zertifikate stehen kurz vor der Erneuerung.

Führen Sie einen regelmäßigen Abgleich aus, der Folgendes prüft:

• Authoritatives DNS und den erwarteten CNAME oder das delegierte Ziel
• Provider-Hostnamen und Zertifikatstatus
• Zertifikatnamen, Ablauf und Erneuerung Health
• Vorhandensein der erforderlichen DNS-Validierungsdatensätze
• Genauer Edge-Route-Besitz und Aktivierungsstatus
• Die aktuelle Berechtigung des Mandanten zur Bereitstellung von Datenverkehr

Die Automatisierung von DNS-validierten Zertifikaten hängt möglicherweise davon ab, dass Validierungs-CNAME-Datensätze öffentlich auflösbar bleiben. Warnung vor Ablauf, anstatt davon auszugehen, dass die automatische Verlängerung immer erfolgreich sein wird.

Verwenden Sie begrenzte Wiederholungsversuche mit exponentiellem Backoff und Jitter für Zertifikatsvorgänge. Behalten Sie das ACME-Konto und den Bestellstatus bei, in dem Sie die Ausgabe direkt durchführen. Wiederholtes Löschen und Wiederherstellen kann die Ratenbegrenzungen für Zertifikatsbestellungen oder registrierte Domänen aufzehren. Ausstehende Hostnamenseinträge verbrauchen möglicherweise auch Anbieterkontingente, bis sie explizit entfernt werden.

Betriebsvorhersage: Ohne Abgleich treten die häufigsten Fehler nach erfolgreichem Onboarding, bei DNS-Änderungen, Zertifikatsverlängerungen, Abweichungen auf Anbieterseite oder Kundenabwanderung auf. Dies ist eine architektonische Erwartung, keine gemessene Fehlerrate.

Offboarding in zwei Phasen

Das Löschen der Datenbankzeile zuerst ist unsicher, da Edge-Mappings, Zertifikate oder DNS dies überdauern können.Verwenden Sie einen überprüfbaren Zwei-Phasen-Workflow:

1. Verschieben Sie die Domäne nach draining und stellen Sie die Werbung für neue Integrationen ein.
2. Entscheiden Sie, ob bestehende Anfragen eine kurze Kulanzfrist oder eine sofortige Ablehnung erhalten.
3. Deaktivieren Sie die Edge-Route, damit der Hostname nicht in einen Standardmandanten aufgelöst werden kann.
4. Entfernen Sie den benutzerdefinierten Hostnamen und die Zertifikatszuordnung aus der Anbieter.
5. Bitten Sie den Kunden, den DNS-Eintrag zu entfernen oder zu ersetzen.
6. Stellen Sie sicher, dass DNS nicht mehr auf Ihren Dienst verweist.
7. Markieren Sie die Ressource deleted und behalten Sie dabei Kennungen und einen Prüfdatensatz bei.

Ein hängender CNAME, der auf einen nicht bereitgestellten Dienst abzielt, kann ein Risiko der Subdomänenübernahme darstellen. Umgekehrt kann das Aktivlassen einer veralteten Zuordnung dazu führen, dass der Datenverkehr eines ehemaligen Kunden weiterhin über Ihren Edge geleitet wird. Kombinieren Sie die Anbieterbereinigung und die DNS-Überprüfung mit demselben Löschvorgang, zeichnen Sie jedoch jedes Ergebnis unabhängig auf.

Testen Sie die Grenze, nicht nur den glücklichen Weg

Bevor Sie Kundendomänen aktivieren, automatisieren Sie Konformitätstests für:

• Einen gefälschten Host- oder X-Forwarded-Host-Header
• Konfliktierende SNI und HTTP Autoritätswerte
• Ein unbekannter Hostname und ein bekannter, aber gesperrter Hostname
• Ein gültiger Schlüssel von Mandant A, der für den Hostnamen von Mandant B verwendet wird
• Doppelte Erstellungs- und Löschanfragen mit demselben Idempotenzschlüssel
• Derselbe Hostname wurde mit Groß-/Kleinschreibung, nachgestelltem Punkt oder Unicode-Varianten übermittelt
• DNS geändert nach der Aktivierung vom erwarteten Ziel entfernt
• Ein entfernter Zertifikatsvalidierungseintrag vor der Erneuerung
• Der Löschvorgang wird unterbrochen, nachdem die Edge-Zuordnung entfernt wurde, aber vor DNS-Änderungen

Überprüfen Sie außerdem, ob Protokolle, Abrechnung, Nutzungszuordnung, Ratenbeschränkungen und Richtlinienentscheidungen Mandanten- und Schlüssel-IDs verwenden. Hostnamen sind veränderbare Präsentations- und Routing-Eingaben; Sie sollten nicht zu Finanz- oder Sicherheitsidentitäten werden.

Checkliste für die Implementierung

• Hostnamen normalisieren und globale Einzigartigkeit erzwingen.
• Eigentum, Zertifikat, DNS und Routenbereitschaft separat verfolgen.
• Zertifikate vor der Umstellung vorab validieren, sofern unterstützt.
• Genaue Autoritäten beim Vertrauenswürdigen auf die Zulassungsliste setzen Edge.
• Entfernen Sie nicht vertrauenswürdige Weiterleitungsheader und erstellen Sie ein authentifiziertes Ursprungssignal.
• Autorisieren Sie den API-Schlüssel für den Mandantenkontext des Hostnamens.
• Verwenden Sie 421 für Ursprungs- oder Verbindungskonflikte und 403 für die mandantenübergreifende Schlüsselverwendung.
• Erstellen und löschen idempotent.
• Anbieterstatus, DNS, Routing und Erneuerungszustand kontinuierlich abgleichen.
• Edge-Zuordnungen explizit löschen und DNS während des Offboardings überprüfen.

Ein Markenendpunkt ist nur bereit, wenn der Status der Steuerungsebene und das Verhalten der Datenebene übereinstimmen.Modellieren Sie diese Vereinbarung explizit, testen Sie die negativen Pfade und behalten Sie den Schlüssel API als endgültige Mandantenautorisierungsgrenze bei.

Verwandte Lektüre

• idempotenter Partner API Operationen