White-Label AI API Končne točke: domene po meri, avtomatizacija TLS in usmerjanje, varno za najemnika

CNAME stranke, ki kaže na vaš prehod, ne ustvari končne točke z blagovno znamko, pripravljene za proizvodnjo. Zapis DNS se lahko razreši, preden je potrdilo na voljo, potrdilo se lahko obnovi samo, medtem ko potrditveni zapisi ostanejo nedotaknjeni, nepreverjena glava Host pa lahko usmeri zahtevo v napačen kontekst najemnika.

Varnejši model je obravnavati vsako ime gostitelja z blagovno znamko kot trajen vir nadzorne ravnine. Lastništvo, izdaja potrdila, prekinitev DNS, aktivacija usmerjanja, začasna ukinitev in brisanje potrebujejo izrecno stanje. V času zahteve ime gostitelja zoži dovoljeni kontekst najemnika, medtem ko ključ API ostane avtorizacijska meja.

Ločite življenjski cikel domene na neodvisna preverjanja

Ne predstavljajte domene po meri z eno logično vrednostjo, kot je verified. Sledite najmanj štirim neodvisnim pogojem:

• Lastništvo: Ali je stranka dokazala nadzor nad imenom gostitelja?
• Certifikat: Ali je bilo veljavno potrdilo izdano in nameščeno na robu?
• DNS: Ali avtoritativni DNS kaže na pričakovani cilj prehoda?
• Usmerjanje: Ali je točno ime gostitelja vezano na aktivni najemnik in profil usmerjanja?

Ta ločitev odraža dokumentirano vedenje robnega ponudnika. Upravljani izdelki z imenom gostitelja po meri lahko uporabljajo različne zapise in statuse za lastništvo imena gostitelja in preverjanje potrdila. Samo razreševanje DNS torej ne dokazuje, da je končna točka pripravljena.

Praktičen stroj stanja je:

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

To so poslovna stanja, ne neposredne kopije statusov ponudnika. Neobdelano stanje ponudnika shranite ločeno, nato pa izpeljite lastno stanje v skladu z dokumentiranimi invariantami. Na primer, označite domeno ready samo, če je lastništvo veljavno, je potrdilo aktivno, DNS kaže na pričakovani cilj in je omogočena robna pot.

Priporočilo: naj bodo prehodi med prvo aktivacijo monotoni. Prehodna uspešna sonda TLS ne sme preskočiti preverjanja lastništva ali usmerjanja. Po aktivaciji lahko usklajevanje premakne domeno iz ready v suspended ali eksplicitno degradirano stanje, ko te invariante prenehajo veljati.

Shranite domeno kot prvorazredni vir

Zapis domene za delujoči prehod AI z belo oznako API mora vsebovati dovolj informacij za obnovitev. ambiguous API calls and 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"
}

Normalizirajte ime gostitelja v male črke ASCII z uporabo knjižnice, ki podpira IDNA, pred preverjanjem edinstvenosti. Odstranite piko na koncu in zavrnite literale IP, poti URL-jev, vrata, nadomestne znake, razen če niso izrecno podprti, in imena zunaj vašega sprejetega pravilnika javnih končnic. Predložen prikazni obrazec ohrani samo kot neavtoritativne metapodatke.

Uveljavi globalno omejitev edinstvenosti za normalizirano ime gostitelja. Dva najemnika nikoli ne smeta imeti možnosti zahtevati istega pooblastila, tudi če uporabljata različne velike začetnice ali predstavitve Unicode.

Predhodno preverite pred spremembo produkcijskega DNS

Če robna platforma to podpira, izdajte in razmestite potrdilo, preden od stranke zahtevate spremembo produkcijskega CNAME.Tipično zaporedje je:

1. Ustvarite sredstvo domene s ključem idempotence.
2. Vrnite zapise o lastništvu in preverjanju potrdil.
3. Vprašajte ali prejemajte dogodke ponudnika, dokler obe potrditvi ne uspeta.
4. Potrdite, da je potrdilo nameščeno za točno ime gostitelja.
5. Prosite stranko, da usmerite produkcijski CNAME na cilj prehoda.
6. Razrešite avtoritativni DNS z več kot ene omrežne lokacije.
7. Omogočite pot in izvedite overjeno sondo od konca do konca.
8. Označite domeno ready.

Dejstvo: upravljano Dokumentacija SaaS-edge opisuje selitvena zaporedja brez izpadov, v katerih se preverjanje veljavnosti in izdaja potrdila izvedeta pred spremembo produkcijskega CNAME. Kompromis: s tem se izognete vidni vrzeli pri aktivaciji TLS, vendar od stranke zahtevate, da ustvari dodatne zapise TXT, CNAME ali delegirane potrditvene zapise.

Če predhodno preverjanje ni na voljo, izrecno izpostavite verjetno prekinitev. Ne obljubljajte ničelnih izpadov, ko se izdaja potrdila začne šele po tem, ko se promet premakne.

Usmerjanje po natančnih pooblastilih, nato avtorizacija ključa

Zaupanja vreden rob mora vzdrževati natančen seznam dovoljenih od imena gostitelja do dovoljenega najemnika ali konteksta blagovne znamke:

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

Zavrni neznana, neaktivna in dvoumna pooblastila. Nikoli jih ne pošiljajte privzetemu najemniku. Za HTTP/1.1 preverite Host; za HTTP/2 in HTTP/3 preverite :authority. Če je TLS prekinjen na istem robu, primerjajte pooblastilo za zahtevo s SNI in kontekstom potrdila, ki ga podpira proxy.

Glave za posredovanje zahtevajo enako disciplino. Javni rob bi moral odstraniti dohodne X-Forwarded-Host, Forwarded in vse notranje glave najemnikov, nato dodati kanoničnega gostitelja in razrešen signal najemnika. Izvor bi moral sprejemati te signale samo prek overjenih povezav od roba do izvora.

Zaporedje avtorizacije med izvajanjem mora biti:

1. Razrešite normalizirano pooblastilo prek seznama dovoljenih aktivnih imen gostiteljev.
2. Neodvisno preverite pristnost ključa API.
3. Naložite nespremenljivi identifikator najemnika priložen ključu.
4. Preverite, ali je najemnik ključa dovoljen na razrešenem imenu gostitelja.
5. Uporabite model, proračun, omejitev stopnje in pravilnik usmerjanja z uporabo ID-jev najemnikov in ključev.
6. Pišite zapise uporabe za te nespremenljive ID-je, ne za ime gostitelja.

To ohrani vlogo Partnerja API avtomatizacije brez spreminjanja operacije upravljanja domene v avtorizacijsko bližnjico.

Vrni 421 Misdirected Request, ko se pooblastilo ne ujema s konfiguriranim izvorom ali kontekstom povezave. Vrni 403 Forbidden, ko je ime gostitelja veljavno, vendar overjen ključ pripada najemniku, ki ga ne sme uporabljati. Tela napak naj bodo dovolj splošna, da ne razkrijejo, kateri najemnik ima ime gostitelja.

Združljivost kanonične končne točke in končne točke z blagovno znamko

Nekatere stranke potrebujejo en ključ za delo na kanonični končni točki prehoda in končni točki z blagovno znamko. To je sprejemljivo le, če se obe imeni gostitelja razrešita v isti pooblaščeni kontekst najemnika.Stroga vezava vsakega ključa na eno ime gostitelja zmanjša uporabo med blagovnimi znamkami, vendar oteži selitve in odjemalce, ki preklapljajo med končnimi točkami.

Priporočilo: modelirajte dovoljene kontekste končnih točk kot pravilnik o ključih in ne primerjajte nizov znotraj kode aplikacije. Ključ lahko na primer dovoljuje tenant:any-active-hostname, brand:brand_42 ali en natančen domain_id.

Izpostavite operacije življenjskega cikla prek partnerja API

Minimalni API mora podpirati ustvarjanje, pregledovanje, ponovno preverjanje, začasno ustavitev, nadaljevanje in brisanje:

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}

Operacije ustvarjanja in brisanja morajo sprejemati stabilne ključe idempotence. API-ji ponudnika, širjenje DNS in časovne omejitve omrežja lahko povzročijo, da klicatelj ni prepričan, ali je operacija uspela. Ohranite zapis operacije, preden prikličete robnega ponudnika, in vrnite isto domeno ali operacijo izbrisa, ko se zahteva znova poskusi z istim ključem in enakovredno obremenitvijo.

Oddajanje podpisanih dogodkov življenjskega cikla, kot so custom_domain.verification_required, custom_domain.certificate_active, custom_domain.ready, custom_domain.dns_drifted, custom_domain.renewal_at_risk in custom_domain.deleted. Dogodki so obvestila, ne edini vir resnice; potrošniki bi morali imeti možnost pridobiti trenutno stanje po zamujeni ali podvojeni dostavi.

Nenehno usklajujte DNS, potrdila in usmerjanje

Aktivacija ni konec življenjskega cikla. Zapisi DNS so urejeni, zapisi za preverjanje veljavnosti izginejo, konfiguracija roba se premakne in potrdila se približajo obnavljanju.

Zaženite periodični usklajevalnik, ki preveri:

• Autoritativni DNS in pričakovani CNAME ali delegirani cilj
• Ime gostitelja ponudnika in stanja potrdila
• Imena potrdil, potek in stanje obnovitve
• Prisotnost zahtevanih zapisov za preverjanje DNS
• Natančno lastništvo robne poti in stanje aktivacije
• Trenutna upravičenost najemnika za oskrbovanje prometa

Avtomatizacija potrdil, potrjena z DNS, je lahko odvisna od potrditvenih zapisov CNAME, ki ostanejo javno dostopni rešljiv. Opozorilo pred potekom namesto predpostavke, da bo samodejno obnavljanje vedno uspelo.

Uporabite omejene ponovne poskuse z eksponentnim odmikom in tresenjem za operacije potrdil. Ohranite račun ACME in stanje naročila, kjer izdajate neposredno. Ponavljajoče se brisanje in ponovno ustvarjanje lahko porabita omejitve naročila potrdila ali hitrosti registrirane domene. Čakajoči zapisi imena gostitelja lahko porabijo tudi kvoto ponudnika, dokler niso izrecno odstranjeni.

Operativno predvidevanje: brez usklajevanja se bodo najpogostejše napake pojavile po uspešnem vkrcanju, med urejanjem DNS, obnovo potrdila, odmikom na strani ponudnika ali odhodom strank. To je arhitekturno pričakovanje, ne izmerjena stopnja napake.

Izklopljeno v dveh fazah

Če najprej izbrišete vrstico zbirke podatkov, ni varno, ker lahko preslikave robov, potrdila ali DNS preživijo.Uporabite revizijski dvofazni potek dela:

1. Premaknite domeno na draining in jo nehajte oglaševati za nove integracije.
2. Odločite se, ali obstoječe zahteve prejmejo kratko podaljšano obdobje ali takojšnjo zavrnitev.
3. Onemogočite robno pot, da se ime gostitelja ne more razrešiti v privzetega najemnika.
4. Odstranite ime gostitelja po meri in povezavo potrdila iz ponudnik.
5. Prosite stranko, da odstrani ali zamenja zapis DNS.
6. Preverite, ali DNS ne kaže več na vašo storitev.
7. Označite vir deleted, medtem ko obdržite identifikatorje in revizijski zapis.

Visbeči CNAME, ki cilja na onemogočeno storitev, lahko ustvari tveganje prevzema poddomene. Nasprotno, če pustite zastarelo preslikavo aktivno, lahko promet prejšnje stranke še naprej pošilja skozi vaš rob. Povežite čiščenje ponudnika in preverjanje DNS z isto operacijo brisanja, vendar zabeležite vsak rezultat neodvisno.

Preizkusite mejo, ne le srečne poti

Preden omogočite domene strank, avtomatizirajte preizkuse skladnosti za:

• Ponarejeno Host ali X-Forwarded-Host header
• Nasprotje SNI in HTTP vrednosti pooblastila
• Neznano ime gostitelja in znano, vendar začasno blokirano ime gostitelja
• Veljaven ključ najemnika A, uporabljen na imenu gostitelja najemnika B
• Podvojene zahteve za ustvarjanje in brisanje z istim ključem idempotence
• Isto ime gostitelja, poslano z male in male črke, zadnja pika ali različice Unicode
• DNS se je po aktivaciji spremenil od pričakovanega cilja
• Odstranjen zapis preverjanja potrdila pred obnovitvijo
• Brisanje je bilo prekinjeno po odstranitvi preslikave robov, vendar pred spremembami DNS

Preverite tudi, ali so dnevniki, obračunavanje, uporaba dodeljevanje, omejitve stopnje in odločitve o politiki uporabljajo ID-je najemnikov in ključev. Imena gostiteljev so spremenljivi vnosi za predstavitev in usmerjanje; ne smejo postati finančne ali varnostne identitete.

Kontrolni seznam za implementacijo

• Normalizirajte imena gostiteljev in uveljavite globalno edinstvenost.
• Ločeno sledite lastništvu, potrdilu, DNS-ju in pripravljenosti poti.
• Preverite potrdila pred prekinitvijo, kjer podprto.
• Dovolite natančna pooblastila na zaupanja vrednem robu.
• Odstranite nezaupljive posredovalne glave in ustvarite overjen izvorni signal.
• Pooblastite ključ API glede na kontekst najemnika imena gostitelja.
• Uporabite 421 za izvor ali neujemanje povezave in 403 za uporaba ključa navzkrižnega najemnika.
• Ustvarjanje in brisanje nastavite za idempotentno.
• Nenehno usklajujte stanje ponudnika, DNS, usmerjanje in stanje obnavljanja.
• Izrecno izbrišite preslikave robov in preverite DNS med odklopom.

Končna točka z blagovno znamko je pripravljena šele, ko je stanje nadzorne ravnine in vedenje podatkovne ravnine se strinjata.Izrecno modelirajte to pogodbo, preizkusite negativne poti in obdržite ključ API kot končno mejo pooblastila najemnika.

Sorodno branje

• idempotent Partner API operations