White-Label AI API krajnje točke: prilagođene domene, TLS automatizacija i usmjeravanje sigurno za stanara

Korisnički CNAME koji pokazuje na vaš pristupnik ne stvara krajnju točku marke spremnu za proizvodnju. DNS zapis se može razriješiti prije nego što certifikat postane dostupan, certifikat se može obnoviti samo dok zapisi provjere valjanosti ostaju netaknuti, a neprovjereno Host zaglavlje može usmjeriti zahtjev u pogrešan kontekst zakupca.

Sigurniji model je tretirati svaki brendirani naziv hosta kao trajni resurs kontrolne razine. Vlasništvo, izdavanje certifikata, prelazak DNS-a, aktivacija usmjeravanja, obustava i brisanje zahtijevaju eksplicitno stanje. U vrijeme zahtjeva, naziv glavnog računala sužava dopušteni kontekst zakupca, dok ključ API ostaje granica autorizacije.

Razdvojite životni ciklus domene na neovisne provjere

Nemojte predstavljati prilagođenu domenu s jednim Booleovim kao što je verified. Pratite najmanje četiri neovisna uvjeta:

• Vlasništvo: Je li kupac dokazao kontrolu nad nazivom glavnog računala?
• Certifikat: Je li važeći certifikat izdan i postavljen na rubu?
• DNS: Ima autoritativni DNS ukazuje na očekivani cilj pristupnika?
• Usmjeravanje: Je li točan naziv glavnog računala povezan s aktivnim zakupcem i profilom usmjeravanja?

Ovo odvajanje odražava dokumentirano ponašanje rubnog pružatelja usluga. Upravljani proizvodi prilagođenog imena glavnog računala mogu koristiti različite zapise i statuse za vlasništvo nad imenom glavnog računala i provjeru valjanosti certifikata. Samo razrješenje DNS-a stoga ne dokazuje da je krajnja točka spremna.

Praktični stroj stanja je:

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

Ovo su poslovna stanja, a ne izravne kopije statusa pružatelja usluga. Odvojeno pohranite neobrađeni status pružatelja, a zatim izvedite vlastito stanje prema dokumentiranim invarijantama. Na primjer, označite domenu ready samo kada je vlasništvo valjano, certifikat aktivan, DNS pokazuje na očekivani cilj, a rubna ruta je omogućena.

Preporuka: neka prijelazi budu monotoni tijekom početne aktivacije. Prolazno uspješna TLS sonda ne bi trebala preskočiti potvrdu vlasništva ili provjere usmjeravanja. Nakon aktivacije, usklađivanje može premjestiti domenu iz ready u suspended ili eksplicitno degradirano stanje kada se te invarijante prestanu održavati.

Pohranite domenu kao prvorazredni resurs

Zapis domene za operativni AI API pristupnik trebao bi sadržavati dovoljno informacija za oporavak 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 naziv glavnog računala na mala slova ASCII koristeći IDNA-svjesnu biblioteku prije provjere jedinstvenosti. Uklonite točku na kraju i odbacite IP literale, URL staze, priključke, zamjenske znakove osim ako nisu eksplicitno podržani, i imena izvan prihvaćenih pravila javnih sufiksa. Sačuvajte dostavljeni obrazac za prikaz samo kao neautoritativne metapodatke.

Nametnite globalno ograničenje jedinstvenosti na normaliziranom nazivu glavnog računala. Dva zakupca nikada ne smiju moći polagati pravo na isto ovlaštenje, čak ni kada koriste različita velika i mala slova ili Unicode prikaze.

Prethodna provjera valjanosti prije promjene proizvodnog DNS-a

Kada rubna platforma to podržava, izdajte i implementirajte certifikat prije nego što tražite od korisnika da promijeni proizvodni CNAME.Tipičan slijed je:

1. Stvorite resurs domene s ključem idempotencije.
2. Vratite zapise o vlasništvu i potvrdi valjanosti certifikata.
3. Provjerite ili primite događaje davatelja dok obje provjere ne uspiju.
4. Potvrdite da je certifikat postavljen za točan naziv glavnog računala.
5. Zamolite korisnika da usmjerite produkcijski CNAME na cilj pristupnika.
6. Razriješite autoritativni DNS s više od jedne mrežne lokacije.
7. Omogućite rutu i izvršite autentificiranu end-to-end probu.
8. Označite domenu ready.

Činjenica: upravlja SaaS-edge dokumentacija opisuje sekvence migracije bez prekida rada u kojima se provjera valjanosti i izdavanje certifikata odvijaju prije promjene proizvodnog CNAME-a. Kompromis: time se izbjegava vidljiva praznina u aktivaciji TLS-a, ali se od korisnika traži da stvori dodatne TXT, CNAME ili delegirane zapise provjere valjanosti.

Ako pretprovjera valjanosti nije dostupna, izričito izložite mogući prekid. Ne obećavajte nulti prekid rada kada izdavanje certifikata započne tek nakon što se promet pokrene.

Usmjerite prema točnom ovlaštenju, a zatim autorizirajte ključ

Pouzdani rub treba održavati točan popis dopuštenih od naziva glavnog računala do dopuštenog stanara ili konteksta marke:

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

Odbaci nepoznata, neaktivna i dvosmislena ovlaštenja. Nikada ih ne šaljite zadanom zakupcu. Za HTTP/1.1 potvrdite Host; za HTTP/2 i HTTP/3 potvrdite :authority. Gdje je TLS prekinut na istom rubu, usporedite autoritet zahtjeva sa SNI i kontekstom certifikata koji podržava proxy.

Zaglavlja za prosljeđivanje zahtijevaju istu disciplinu. Javni rub bi trebao ukloniti dolazne X-Forwarded-Host, Forwarded i sva interna zaglavlja stanara, zatim dodati kanonski host i riješeni signal stanara. Izvor bi trebao prihvaćati te signale samo preko provjerenih veza od ruba do izvora.

Slijed autorizacije za vrijeme izvođenja trebao bi biti:

1. Razriješiti normalizirano ovlaštenje putem popisa dopuštenih aktivnih naziva hosta.
2. Nezavisno provjeriti autentičnost ključa API.
3. Učitaj nepromjenjivi identifikator stanara priložen ključu.
4. Provjerite je li stanar ključa dopušten na riješenom nazivu glavnog računala.
5. Primijenite model, proračun, ograničenje stope i politiku usmjeravanja koristeći ID-ove zakupca i ključa.
6. Pišite zapise o korištenju uz te nepromjenjive ID-ove, a ne na naziv glavnog računala.

Ovo zadržava ulogu Partnera API automatizacije bez pretvaranja operacije upravljanja domenom u autorizacijski prečac.

Povratak 421 Misdirected Request kada ovlaštenje ne odgovara konfiguriranom izvoru ili kontekstu veze. Vrati 403 Forbidden kada je naziv glavnog računala važeći, ali autentificirani ključ pripada zakupcu kojemu nije dopušteno koristiti ga. Održavajte tijela pogrešaka dovoljno generičkim da ne otkriju koji zakupac posjeduje naziv glavnog računala.

Kompatibilnost kanonske krajnje točke s markom

Neki korisnici trebaju jedan ključ za rad i na kanonskoj krajnjoj točki pristupnika i na svojoj krajnjoj točki marke. To je prihvatljivo samo kada se oba naziva hosta rješavaju u isti ovlašteni kontekst stanara.Strogo vezanje svakog ključa s jednim nazivom glavnog računala smanjuje korištenje različitih robnih marki, ali komplicira migracije i klijente koji se prebacuju između krajnjih točaka.

Preporuka: modelirajte dopuštene kontekste krajnjih točaka kao pravilo ključeva umjesto usporedbe nizova unutar koda aplikacije. Na primjer, ključ može dopustiti tenant:any-active-hostname, brand:brand_42 ili jedan točan domain_id.

Operacije životnog ciklusa izložiti putem partnera API

Minimalni API trebao bi podržavati stvaranje, provjeru, ponovnu provjeru valjanosti, obustavu, nastavak i 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 stvaranja i brisanja trebaju prihvaćati stabilne ključeve idempotencije. API-ji pružatelja usluga, širenje DNS-a i istek vremena mreže mogu ostaviti pozivatelja nesigurnim je li operacija uspjela. Ustrajte u zapisu operacije prije pozivanja rubnog pružatelja i vratite istu domenu ili operaciju brisanja kada se zahtjev ponovno pokuša s istim ključem i ekvivalentnim opterećenjem.

Emitirajte potpisane događaje životnog ciklusa kao što su custom_domain.verification_required, custom_domain.certificate_active, custom_domain.ready, custom_domain.dns_drifted, custom_domain.renewal_at_risk i custom_domain.deleted. Događaji su obavijesti, a ne jedini izvor istine; potrošači bi trebali moći dohvatiti trenutno stanje nakon propuštene ili duplicirane isporuke.

Kontinuirano uskladite DNS, certifikate i usmjeravanje

Aktivacija nije kraj životnog ciklusa. DNS zapisi se uređuju, zapisi o provjeri valjanosti nestaju, rubna konfiguracija se pomiče, a certifikati se približavaju obnavljanju.

Pokrenite periodično usklađivanje koje provjerava:

• Autoritativan DNS i očekivani CNAME ili delegirani cilj
• Naziv hosta davatelja usluga i statuse certifikata
• Nazivi certifikata, istek i stanje obnove
• Prisutnost potrebnih zapisa provjere valjanosti DNS-a
• Točno vlasništvo rubne rute i stanje aktivacije
• Trenutačna podobnost zakupca za posluživanje prometa

Automatizacija certifikata potvrđena DNS-om može ovisiti o validacijskim CNAME zapisima koji ostaju javno objavljeni razrješiv. Upozorenje prije isteka umjesto pretpostavke da će automatska obnova uvijek uspjeti.

Koristite ograničene ponovne pokušaje s eksponencijalnim odmakom i podrhtavanjem za operacije certifikata. Sačuvajte ACME račun i stanje narudžbe gdje izravno upravljate izdavanjem. Opetovano brisanje i ponovno stvaranje mogu potrošiti ograničenja narudžbe certifikata ili stope registrirane domene. Zapisi naziva hosta na čekanju također mogu zauzeti kvotu pružatelja dok se eksplicitno ne uklone.

Operativno predviđanje: bez usklađivanja, najčešći kvarovi pojavit će se nakon uspješnog uključivanja, tijekom uređivanja DNS-a, obnove certifikata, odstupanja na strani pružatelja ili odlaska korisnika. Ovo je arhitektonsko očekivanje, a ne izmjerena stopa neuspjeha.

Offboard u dvije faze

Prvo brisanje retka baze podataka nije sigurno jer ga rubna mapiranja, certifikati ili DNS mogu nadživjeti.Upotrijebite revizijski dvofazni tijek rada:

1. Premjestite domenu na draining i prestanite je oglašavati za nove integracije.
2. Odlučite hoće li postojeći zahtjevi dobiti kratko razdoblje odgode ili trenutno odbijanje.
3. Onemogućite rubnu rutu tako da se naziv glavnog računala ne može razriješiti u zadanog stanara.
4. Uklonite prilagođeni naziv glavnog računala i povezanost certifikata iz davatelj.
5. Zamolite kupca da ukloni ili zamijeni DNS zapis.
6. Provjerite da DNS više ne ukazuje na vašu uslugu.
7. Označite resurs deleted uz zadržavanje identifikatora i revizijskog zapisa.

Viseći CNAME koji cilja na deproviziranu uslugu može stvoriti rizik preuzimanja poddomena. Suprotno tome, ostavljanje aktivnog ustajalog mapiranja može nastaviti slati promet bivšeg korisnika kroz vaš rub. Povežite čišćenje pružatelja i provjeru DNS-a s istom operacijom brisanja, ali zabilježite svaki rezultat neovisno.

Testirajte granicu, a ne samo sretan put

Prije nego što omogućite korisničke domene, automatizirajte testove usklađenosti za:

• Krivotvoreni Host ili X-Forwarded-Host zaglavlje
• Sukobljeni SNI i HTTP vrijednosti ovlaštenja
• Nepoznato ime glavnog računala i poznato, ali suspendirano ime glavnog računala
• Valjani ključ stanara A upotrijebljen na nazivu glavnog računala stanara B
• Duplicirani zahtjevi za stvaranje i brisanje s istim ključem idempotencije
• Isti naziv glavnog računala dostavljen s velika i mala slova, točka na kraju ili Unicode varijacije
• DNS se promijenio u odnosu na očekivani cilj nakon aktivacije
• Uklonjen zapis provjere valjanosti certifikata prije obnove
• Brisanje je prekinuto nakon što je mapiranje ruba uklonjeno, ali prije promjena DNS-a

Također provjerite zapise, naplatu, upotrebu atribucija, ograničenja stope i odluke o politici koriste ID-ove stanara i ključa. Imena hostova su promjenjivi ulazi za prezentaciju i usmjeravanje; ne bi trebali postati financijski ili sigurnosni identiteti.

Kontrolni popis za implementaciju

• Normalizirajte nazive hostova i nametnite globalnu jedinstvenost.
• Odvojeno pratite vlasništvo, certifikat, DNS i spremnost rute.
• Prethodna provjera valjanosti certifikata prije prekidanja gdje podržano.
• Popis dopuštenih točnih ovlaštenja na pouzdanom rubu.
• Uklonite nepouzdana zaglavlja za prosljeđivanje i stvorite autentificirani izvorni signal.
• Autorizirajte ključ API prema kontekstu zakupca naziva glavnog računala.
• Koristite 421 za izvor ili neusklađenost veze i 403 za upotreba ključa među zakupcima.
• Učinite kreiranje i brisanje idempotentnim.
• Uskladite stanje pružatelja usluga, DNS, usmjeravanje i stanje obnavljanja kontinuirano.
• Izričito izbrišite preslikavanja rubova i provjerite DNS tijekom isključivanja.

Brendirana krajnja točka spremna je samo kada je stanje kontrolne ravnine i ponašanje podatkovne ravnine se slažu.Eksplicitno modelirajte taj ugovor, testirajte negativne putanje i zadržite ključ API kao konačnu granicu autorizacije stanara.

Povezano čitanje

• idempotentni partner API operacije