Endpoint AI API white label: domini personalizzati, automazione TLS e routing sicuro per i tenant

Un CNAME del cliente che punta al tuo gateway non crea un endpoint brandizzato pronto per la produzione. Il record DNS potrebbe risolversi prima che un certificato sia disponibile, il certificato potrebbe rinnovarsi solo mentre i record di convalida rimangono intatti e un'intestazione Host non controllata può instradare una richiesta nel contesto del tenant sbagliato.

Il modello più sicuro consiste nel trattare ogni nome host con marchio come una risorsa durevole del piano di controllo. La proprietà, l'emissione del certificato, il cutover DNS, l'attivazione del routing, la sospensione e l'eliminazione richiedono ciascuno uno stato esplicito. Al momento della richiesta, il nome host restringe il contesto del tenant consentito, mentre la chiave API rimane il limite dell'autorizzazione.

Separa il ciclo di vita del dominio in controlli indipendenti

Non rappresentare un dominio personalizzato con un singolo valore booleano come verified. Tieni traccia almeno di quattro condizioni indipendenti:

• Proprietà: Il cliente ha dimostrato il controllo del nome host?
• Certificato: È stato emesso e distribuito un certificato valido all'edge?
• DNS: Il DNS autorevole punta al server previsto destinazione gateway?
• Routing: Il nome host esatto è associato a un tenant attivo e a un profilo di routing?

Questa separazione riflette il comportamento documentato del provider edge. I prodotti gestiti con nome host personalizzato possono utilizzare record e stati diversi per la proprietà del nome host e la convalida del certificato. La sola risoluzione DNS pertanto non dimostra che l'endpoint è pronto.

Una macchina a stati pratica è:

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

Questi sono stati aziendali, non copie dirette degli stati del provider. Memorizza lo stato grezzo del provider separatamente, quindi ricava il tuo stato in base alle invarianti documentate. Ad esempio, contrassegna un dominio ready solo quando la proprietà è valida, il certificato è attivo, il DNS punta alla destinazione prevista e l'edge route è abilitato.

Raccomandazione: rendi monotone le transizioni durante l'attivazione iniziale. Un'indagine TLS transitoria riuscita non deve ignorare la convalida della proprietà o i controlli di instradamento. Dopo l'attivazione, la riconciliazione potrebbe spostare un dominio da ready a suspended o uno stato esplicito degradato quando tali invarianti smettono di essere mantenuti.

Memorizza un dominio come risorsa di prima classe

Un record di dominio per un AI white label operativo API gateway dovrebbe contenere informazioni sufficienti per il ripristino da API chiamate e provider ambigui 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"
}

Normalizza il nome host in ASCII minuscolo utilizzando una libreria compatibile con IDNA prima dei controlli di unicità. Rimuovi un punto finale e rifiuta valori letterali IP, percorsi URL, porte, caratteri jolly a meno che non siano esplicitamente supportati e nomi al di fuori dei criteri di suffisso pubblico accettati. Conserva il modulo di visualizzazione inviato solo come metadati non autorevoli.

Applica un vincolo di unicità globale sul nome host normalizzato. Due tenant non devono mai essere in grado di rivendicare la stessa autorità, anche quando utilizzano lettere maiuscole o rappresentazioni Unicode diverse.

Preconvalida prima di modificare il DNS di produzione

Se la piattaforma perimetrale lo supporta, emetti e distribuisci il certificato prima di chiedere al cliente di modificare il CNAME di produzione.Una sequenza tipica è:

1. Crea la risorsa del dominio con una chiave di idempotenza.
2. Restituisci i record di proprietà e di convalida del certificato.
3. Esegui il polling o ricevi eventi del provider finché entrambe le convalide non hanno esito positivo.
4. Conferma che il certificato è stato distribuito per il nome host esatto.
5. Chiedi al cliente di indirizzare il CNAME di produzione al gateway target.
6. Risolvi DNS autorevole da più di una posizione di rete.
7. Abilita il percorso ed esegui un'analisi end-to-end autenticata.
8. Contrassegna il dominio ready.

Fatto: la documentazione SaaS-edge gestita descrive sequenze di migrazione senza tempi di inattività in cui la convalida e l'emissione del certificato avvengono prima delle modifiche del CNAME di produzione. Compromesso: questo evita un gap visibile di attivazione TLS ma richiede al cliente di creare ulteriori record TXT, CNAME o di convalida delegata.

Se la preconvalida non è disponibile, esponi esplicitamente la probabile interruzione. Non promettere tempi di inattività pari a zero quando l'emissione del certificato inizia solo dopo che il traffico si è spostato.

Instrada in base all'autorità esatta, quindi autorizza la chiave

L'edge attendibile deve mantenere una lista consentita esatta dal nome host al tenant consentito o al contesto del brand:

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

Rifiuta autorità sconosciute, inattive e ambigue. Non inviarli mai a un inquilino predefinito. Per HTTP/1.1, convalida Host; per HTTP/2 e HTTP/3, convalida :authority. Laddove TLS termina sullo stesso edge, confronta l'autorità di richiesta con l'SNI e il contesto del certificato supportati dal proxy.

Le intestazioni di inoltro richiedono la stessa disciplina. Il perimetro pubblico dovrebbe rimuovere X-Forwarded-Host, Forwarded in entrata ed eventuali intestazioni del tenant interno, quindi aggiungere un host canonico e un segnale del tenant risolto. L'origine deve accettare tali segnali solo tramite connessioni edge-to-origin autenticate.

La sequenza di autorizzazione di runtime deve essere:

1. Risolvi l'autorità normalizzata tramite la lista consentita del nome host attivo.
2. Autentica la chiave API in modo indipendente.
3. Carica l'identificatore del tenant immutabile collegato al key.
4. Verifica che il tenant della chiave sia consentito sul nome host risolto.
5. Applica modello, budget, limite di velocità e policy di routing utilizzando gli ID tenant e chiave.
6. Scrivi i record di utilizzo rispetto a tali ID immutabili, non al nome host.

In questo modo viene preservato il ruolo di Partner API automazione senza trasformare un'operazione di gestione del dominio in una scorciatoia di autorizzazione.

Restituisce 421 Misdirected Request quando l'autorità non corrisponde all'origine configurata o al contesto di connessione. Restituisce 403 Forbidden quando il nome host è valido ma la chiave autenticata appartiene a un tenant a cui non è consentito utilizzarlo. Mantieni i corpi degli errori abbastanza generici da non rivelare quale tenant possiede un nome host.

Compatibilità tra endpoint canonico e brandizzato

Alcuni clienti necessitano di una chiave per funzionare sia sull'endpoint canonico del gateway che sul proprio endpoint brandizzato. Ciò è accettabile solo quando entrambi i nomi host si risolvono nello stesso contesto di tenant autorizzato.Associare rigorosamente ciascuna chiave a un nome host riduce l'utilizzo di più marchi, ma complica le migrazioni e i client che passano da un endpoint all'altro.

Raccomandazione: il modello consentiva contesti endpoint come policy chiave anziché confrontare stringhe all'interno del codice dell'applicazione. Ad esempio, una chiave può consentire tenant:any-active-hostname, brand:brand_42 o un domain_id esatto.

Esponi le operazioni del ciclo di vita tramite il partner API

Un API minimo dovrebbe supportare la creazione, l'ispezione, la riconvalida, la sospensione, la ripresa e l'eliminazione:

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}

Le operazioni di creazione ed eliminazione dovrebbero accettare chiavi di idempotenza stabili. Le API del provider, la propagazione DNS e i timeout di rete possono lasciare il chiamante incerto se un'operazione è riuscita. Mantieni il record dell'operazione prima di richiamare il provider edge e restituisce lo stesso dominio o l'operazione di eliminazione quando la richiesta viene ritentata con la stessa chiave e payload equivalente.

Emette eventi del ciclo di vita firmati come custom_domain.verification_required, custom_domain.certificate_active, custom_domain.ready, custom_domain.dns_drifted, custom_domain.renewal_at_risk e custom_domain.deleted. Gli eventi sono notifiche, non l'unica fonte di verità; i consumatori dovrebbero essere in grado di recuperare lo stato corrente dopo una consegna mancata o duplicata.

Riconcilia DNS, certificati e routing in modo continuo

L'attivazione non è la fine del ciclo di vita. I record DNS vengono modificati, i record di convalida scompaiono, la configurazione dei bordi si sposta e i certificati si avvicinano al rinnovo.

Esegui una riconciliazione periodica che controlla:

• DNS autorevole e CNAME previsto o destinazione delegata
• Nome host del provider e stati dei certificati
• Nomi dei certificati, scadenza e rinnovo integrità
• Presenza di record di convalida DNS richiesti
• Proprietà esatta del percorso edge e stato di attivazione
• L'attuale idoneità del tenant a gestire il traffico

L'automazione dei certificati convalidati DNS può dipendere dal fatto che i record CNAME di convalida rimangano risolvibili pubblicamente. Avvisa prima della scadenza invece di dare per scontato che il rinnovo automatico avrà sempre esito positivo.

Utilizza tentativi limitati con backoff esponenziale e jitter per le operazioni sui certificati. Conserva l'account ACME e lo stato dell'ordine in cui gestisci direttamente l'emissione. L'eliminazione e la ricreazione ripetute possono consumare limiti di velocità relativi all'ordine di certificato o al dominio registrato. I record di nomi host in sospeso potrebbero anche consumare la quota del provider finché non verranno rimossi esplicitamente.

Previsione operativa: senza riconciliazione, gli errori più comuni verranno visualizzati dopo l'onboarding riuscito, durante le modifiche DNS, il rinnovo del certificato, la deriva lato provider o l'abbandono dei clienti. Si tratta di un'aspettativa architetturale, non di un tasso di fallimento misurato.

Offboard in due fasi

Eliminare prima la riga del database non è sicuro perché le mappature dei bordi, i certificati o il DNS possono sopravvivere.Utilizza un flusso di lavoro in due fasi controllabile:

1. Sposta il dominio in draining e smetti di pubblicizzarlo per nuove integrazioni.
2. Decidi se le richieste esistenti riceveranno un breve periodo di grazia o un rifiuto immediato.
3. Disabilita l'edge route in modo che il nome host non possa risolversi in un tenant predefinito.
4. Rimuovi il nome host personalizzato e l'associazione del certificato dal provider.
5. Chiedi al cliente di rimuovere o sostituire il record DNS.
6. Verifica che il DNS non punti più al tuo servizio.
7. Contrassegna la risorsa deleted conservando gli identificatori e un record di controllo.

Un CNAME pendente che prende di mira un servizio di cui è stato effettuato il deprovisioning può creare un rischio di acquisizione del sottodominio. Al contrario, lasciare attiva una mappatura obsoleta può continuare a inviare il traffico di un ex cliente attraverso il tuo perimetro. Associa la pulizia del provider e la verifica DNS alla stessa operazione di eliminazione, ma registra ogni risultato in modo indipendente.

Verifica il confine, non solo il percorso felice

Prima di abilitare i domini dei clienti, automatizza i test di conformità per:

• Un'intestazione Host o X-Forwarded-Host contraffatta
• Conflitto SNI e HTTP autorità valori
• Un nome host sconosciuto e un nome host noto ma sospeso
• Una chiave valida del tenant A utilizzata sul nome host del tenant B
• Richieste di creazione ed eliminazione duplicate con la stessa chiave di idempotenza
• Lo stesso nome host inviato con maiuscole e minuscole, punti finali o varianti Unicode
• DNS modificato rispetto a quello previsto target dopo l'attivazione
• Un record di convalida del certificato rimosso prima del rinnovo
• Eliminazione interrotta dopo la rimozione della mappatura dei bordi ma prima delle modifiche DNS

Verifica inoltre che log, fatturazione, attribuzione di utilizzo, limiti di velocità e decisioni relative alle policy utilizzino ID tenant e chiave. I nomi host sono presentazioni mutabili e input di routing; non devono diventare identità finanziarie o di sicurezza.

Elenco di controllo per l'implementazione

• Normalizza i nomi host e applica l'unicità globale.
• Monitora separatamente proprietà, certificato, DNS e disponibilità del percorso.
• Preconvalida i certificati prima del cutover, ove supportato.
• Inserisci nella lista consentita le autorità esatte presso le autorità attendibili edge.
• Elimina le intestazioni di inoltro non attendibili e crea un segnale di origine autenticato.
• Autorizza la chiave API rispetto al contesto tenant del nome host.
• Utilizza 421 per la mancata corrispondenza dell'origine o della connessione e 403 per l'utilizzo della chiave tra tenant.
• Crea ed elimina idempotente.
• Riconcilia continuamente lo stato del provider, il DNS, il routing e l'integrità del rinnovo.
• Elimina esplicitamente le mappature dei bordi e verifica il DNS durante l'offboarding.

Un endpoint brandizzato è pronto solo quando lo stato del piano di controllo e il comportamento del piano dati concordano.Modella il contratto in modo esplicito, testa i percorsi negativi e mantieni la chiave API come limite finale dell'autorizzazione del tenant.

Lettura correlata

• Partner idempotente API operazioni