White-Label AI API-eindpunten: aangepaste domeinen, TLS-automatisering en tenantveilige routering

Een klant-CNAME die naar uw gateway verwijst, creëert geen productieklaar merkeindpunt. Het DNS-record kan worden opgelost voordat er een certificaat beschikbaar is, het certificaat kan alleen worden vernieuwd zolang de validatierecords intact blijven, en een niet-aangevinkte Host-header kan een verzoek naar de verkeerde tenantcontext routeren.

Het veiligere model is om elke merkhostnaam te behandelen als een duurzame bron op het controlevlak. Eigendom, uitgifte van certificaten, DNS-cutover, routeringsactivering, opschorting en verwijdering hebben elk een expliciete status nodig. Op het moment van de aanvraag beperkt de hostnaam de toegestane tenantcontext, terwijl de API-sleutel de autorisatiegrens blijft.

Verdeel de domeinlevenscyclus in onafhankelijke controles

Representeer geen aangepast domein met een enkele Booleaanse waarde, zoals verified. Houd minimaal vier onafhankelijke voorwaarden bij:

• Eigendom: Heeft de klant bewezen controle te hebben over de hostnaam?
• Certificaat: Is er een geldig certificaat uitgegeven en geïmplementeerd aan de edge?
• DNS: Wijst gezaghebbende DNS op de verwachte gatewaydoel?
• Routing: Is de exacte hostnaam gebonden aan een actieve tenant en een routeringsprofiel?

Deze scheiding weerspiegelt het gedocumenteerde gedrag van de edge-provider. Beheerde aangepaste hostnaamproducten kunnen verschillende records en statussen gebruiken voor hostnaameigendom en certificaatvalidatie. DNS-resolutie alleen bewijst daarom niet dat het eindpunt gereed is.

Een praktische statusmachine is:

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

Dit zijn bedrijfsstatussen, geen directe kopieën van providerstatussen. Sla de onbewerkte status van de provider afzonderlijk op en leid vervolgens uw eigen status af op basis van gedocumenteerde invarianten. Markeer bijvoorbeeld een domein ready alleen als het eigendom geldig is, het certificaat actief is, DNS naar het verwachte doel verwijst en de edge-route is ingeschakeld.

Aanbeveling: zorg ervoor dat overgangen monotoon zijn tijdens de initiële activering. Bij een tijdelijke succesvolle TLS-test mag de eigendomsvalidatie of routeringscontroles niet worden overgeslagen. Na activering kan de afstemming een domein verplaatsen van ready naar suspended of een expliciet gedegradeerde status krijgen wanneer deze invarianten niet meer behouden blijven.

Een domein opslaan als een eersteklas hulpbron

Een domeinrecord voor een operationele white-label AI API gateway moet voldoende informatie bevatten om te herstellen van dubbelzinnige API oproepen en provider 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"
}

Normaliseer de hostnaam naar kleine ASCII-letters met behulp van een IDNA-bewuste bibliotheek vóór uniciteitscontroles. Verwijder een volgpunt en wijs IP-literals, URL-paden, poorten, jokertekens af, tenzij expliciet ondersteund, en namen buiten uw geaccepteerde beleid voor openbare achtervoegsels. Bewaar het ingediende weergaveformulier alleen als niet-gezaghebbende metadata.

Dwing een globale uniekheidsbeperking op voor de genormaliseerde hostnaam. Twee tenants mogen nooit dezelfde autoriteit kunnen claimen, zelfs niet als ze verschillend hoofdlettergebruik of Unicode-representaties gebruiken.

Prevalideren voordat de productie-DNS wordt gewijzigd

Als het edge-platform dit ondersteunt, geeft u het certificaat uit en implementeert u het voordat u de klant vraagt ​​de productie-CNAME te wijzigen.Een typische reeks is:

1. Maak de domeinbron met een idempotentiesleutel.
2. Retourneer de eigendoms- en certificaatvalidatierecords.
3. Poll of ontvang providergebeurtenissen totdat beide validaties slagen.
4. Bevestig dat het certificaat is geïmplementeerd voor de exacte hostnaam.
5. Vraag de klant om de productie-CNAME naar de gateway te verwijzen target.
6. Repareer gezaghebbende DNS van meer dan één netwerklocatie.
7. Schakel de route in en voer een geverifieerde end-to-end test uit.
8. Markeer het domein ready.

Feit: beheerde SaaS-edge-documentatie beschrijft migratiereeksen zonder downtime waarin validatie en certificaatuitgifte vinden plaats voordat de productie-CNAME verandert. Trade-off: dit vermijdt een zichtbare TLS-activeringskloof, maar vereist dat de klant extra TXT-, CNAME- of gedelegeerde validatierecords maakt.

Als prevalidatie niet beschikbaar is, maak de waarschijnlijke onderbreking dan expliciet bekend. Beloof geen nul-downtime als de uitgifte van certificaten pas begint nadat het verkeer is verplaatst.

Route op exacte autoriteit en autoriseer vervolgens de sleutel

De vertrouwde rand moet een exacte toelatingslijst bijhouden, van hostnaam tot toegestane tenant- of merkcontext:

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

Weiger onbekende, inactieve en dubbelzinnige autoriteiten. Stuur ze nooit naar een standaardtenant. Voor HTTP/1.1, valideer Host; voor HTTP/2 en HTTP/3, valideer :authority. Als TLS aan dezelfde rand wordt beëindigd, vergelijk dan de verzoekautoriteit met de SNI- en certificaatcontext zoals ondersteund door de proxy.

Voor het doorsturen van headers is dezelfde discipline vereist. De openbare rand moet binnenkomend X-Forwarded-Host, Forwarded en eventuele interne tenantheaders verwijderen en vervolgens een canonieke host en een opgelost tenantsignaal toevoegen. De oorsprong mag deze signalen alleen accepteren via geverifieerde edge-to-origin-verbindingen.

De runtime-autorisatievolgorde moet als volgt zijn:

1. Los de genormaliseerde autoriteit op via de actieve hostnaam-toelatingslijst.
2. Authenticeer de API-sleutel onafhankelijk.
3. Laad de onveranderlijke tenant-ID die is gekoppeld aan de key.
4. Controleer of de tenant van de sleutel is toegestaan op de opgeloste hostnaam.
5. Pas model-, budget-, tarieflimiet- en routeringsbeleid toe met behulp van tenant- en sleutel-ID's.
6. Schrijf gebruiksrecords op basis van deze onveranderlijke ID's, niet op de hostnaam.

Hierdoor blijft de rol van Partner API behouden automatisering zonder een domeinbeheerbewerking om te zetten in een autorisatiesnelkoppeling.

Retourneer 421 Misdirected Request wanneer de autoriteit niet overeenkomt met de geconfigureerde oorsprong of verbindingscontext. Retourneert 403 Forbidden wanneer de hostnaam geldig is, maar de geverifieerde sleutel toebehoort aan een tenant die deze niet mag gebruiken. Houd de foutteksten generiek genoeg zodat ze niet onthullen welke tenant eigenaar is van een hostnaam.

Compatibiliteit met canonieke en merkeindpunten

Sommige klanten hebben één sleutel nodig om te werken aan zowel het canonieke eindpunt van de gateway als aan hun merkeindpunt. Dat is alleen acceptabel als beide hostnamen worden omgezet in dezelfde geautoriseerde tenantcontext.Het strikt binden van elke sleutel aan één hostnaam vermindert het gebruik tussen merken, maar compliceert migraties en clients die tussen eindpunten schakelen.

Aanbeveling: het model stond eindpuntcontexten toe als sleutelbeleid in plaats van tekenreeksen binnen de applicatiecode te vergelijken. Een sleutel kan bijvoorbeeld tenant:any-active-hostname, brand:brand_42 of één exacte domain_id toestaan.

Levencyclusbewerkingen zichtbaar maken via de partner API

Een minimale API moet het maken, inspecteren, opnieuw valideren, opschorten, hervatten en verwijderen ondersteunen:

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}

Het maken en verwijderen van bewerkingen moet stabiele idempotentiesleutels accepteren. Provider-API's, DNS-doorgifte en netwerktime-outs kunnen ervoor zorgen dat de aanroeper niet zeker weet of een bewerking is geslaagd. Bewaar de bewerkingsrecord voordat u de edge-provider aanroept, en retourneer hetzelfde domein of dezelfde verwijderingsbewerking wanneer het verzoek opnieuw wordt geprobeerd met dezelfde sleutel en gelijkwaardige payload.

Verzend ondertekende levenscyclusgebeurtenissen zoals custom_domain.verification_required, custom_domain.certificate_active, custom_domain.ready, custom_domain.dns_drifted, custom_domain.renewal_at_risk en custom_domain.deleted. Gebeurtenissen zijn meldingen, niet de enige bron van waarheid; consumenten moeten de huidige status kunnen ophalen na gemiste of dubbele bezorging.

Reconcilieer DNS, certificaten en routering voortdurend

Activering is niet het einde van de levenscyclus. DNS-records worden bewerkt, validatierecords verdwijnen, edge-configuratie wijkt af en certificaten worden vernieuwd.

Voer een periodieke reconciler uit die het volgende controleert:

• Authoritatieve DNS en het verwachte CNAME of gedelegeerde doel
• Hostnaam en certificaatstatus van provider
• Certificaatnamen, vervaldatum en verlenging health
• Aanwezigheid van vereiste DNS-validatierecords
• Exacte edge-route-eigendom en activeringsstatus
• De huidige geschiktheid van de tenant om verkeer te leveren

Automatisering van DNS-gevalideerde certificaten kan afhankelijk zijn van de mate waarin validatie-CNAME-records openbaar oplosbaar blijven. Waarschuw vóór de vervaldatum in plaats van ervan uit te gaan dat automatische verlenging altijd zal slagen.

Gebruik begrensde nieuwe pogingen met exponentieel uitstel en jitter voor certificaatbewerkingen. Bewaar het ACME-account en de bestelstatus waar u de uitgifte rechtstreeks beheert. Herhaaldelijk verwijderen en opnieuw aanmaken kan de snelheidslimieten voor certificaatbestellingen of geregistreerde domeinen in beslag nemen. Hostnaamrecords die in behandeling zijn, kunnen ook providerquota verbruiken totdat ze expliciet worden verwijderd.

Operationele voorspelling: zonder afstemming zullen de meest voorkomende fouten optreden na succesvolle onboarding, tijdens DNS-bewerkingen, certificaatvernieuwing, drift aan de providerzijde of klantverloop. Dit is een architecturale verwachting, geen gemeten foutpercentage.

Offboard in twee fasen

Het eerst verwijderen van de databaserij is onveilig omdat edge-toewijzingen, certificaten of DNS deze kunnen overleven.Gebruik een controleerbare werkstroom in twee fasen:

1. Verplaats het domein naar draining en stop met het promoten ervan voor nieuwe integraties.
2. Bepaal of bestaande verzoeken een korte respijtperiode krijgen of onmiddellijk worden afgewezen.
3. Schakel de edge-route uit zodat de hostnaam niet kan worden omgezet in een standaardtenant.
4. Verwijder de aangepaste hostnaam en certificaatkoppeling uit de provider.
5. Vraag de klant om de DNS-record te verwijderen of te vervangen.
6. Controleer of DNS niet langer naar uw service verwijst.
7. Markeer de bron deleted met behoud van ID's en een auditrecord.

Een bungelende CNAME die zich richt op een uitgeschreven service, kan een risico op subdomeinovername met zich meebrengen. Omgekeerd kan het actief laten van een verouderde mapping het verkeer van een voormalige klant door uw edge blijven sturen. Koppel het opschonen van de provider en de DNS-verificatie aan dezelfde verwijderingsbewerking, maar registreer elk resultaat afzonderlijk.

Test de grens, niet alleen het goede pad

Automatiseer conformiteitstesten voordat u klantdomeinen inschakelt voor:

• Een vervalste Host of X-Forwarded-Host header
• Conflicterende SNI en HTTP autoriteitswaarden
• Een onbekende hostnaam en een bekende maar opgeschorte hostnaam
• Een geldige sleutel van tenant A gebruikt op de hostnaam van tenant B
• Dubbele aanmaak- en verwijderingsverzoeken met dezelfde idempotentiesleutel
• Dezelfde hostnaam ingediend met hoofdletter-, punt- of Unicode-varianten
• DNS is gewijzigd van het verwachte doel na activering
• Een verwijderde certificaatvalidatierecord vóór verlenging
• Verwijdering onderbroken nadat de edge-toewijzing is verwijderd maar vóór DNS-wijzigingen

Controleer ook of logboeken, facturering, gebruikstoeschrijving, tarieflimieten en beleidsbeslissingen gebruik maken van tenant- en sleutel-ID's. Hostnamen zijn veranderlijke presentatie- en routeringsinvoer; ze mogen geen financiële of beveiligingsidentiteiten worden.

Implementatiechecklist

• Hostnamen normaliseren en globale uniciteit afdwingen.
• Eigendom, certificaat, DNS en routegereedheid afzonderlijk bijhouden.
• Prevalideer certificaten vóór de overgang waar dit wordt ondersteund.
• Toestaan van exacte autoriteiten bij de vertrouwde edge.
• Verwijder niet-vertrouwde doorstuurheaders en maak een geverifieerd oorsprongssignaal.
• Autoriseer de API-sleutel voor de tenantcontext van de hostnaam.
• Gebruik 421 voor niet-overeenkomende oorsprong of verbinding en 403 voor sleutelgebruik tussen meerdere tenants.
• Maken en verwijderen idempotent.
• Vergelijk de status van de provider, DNS, routing en vernieuwingsstatus voortdurend.
• Verwijder edge-toewijzingen expliciet en verifieer DNS tijdens offboarding.

Een merkeindpunt is alleen gereed als de status van het controlevlak en het gedrag van het datavlak ermee instemmen.Modelleer die overeenkomst expliciet, test de negatieve paden en behoud de sleutel API als de uiteindelijke grens voor de autorisatie van de tenant.

Gerelateerd lezen

• idempotent Partner API operations