Endpoints de IA API de marca branca: domínios personalizados, automação TLS e roteamento seguro para locatários

Um CNAME de cliente apontando para seu gateway não cria um endpoint com marca pronto para produção. O registro DNS pode ser resolvido antes que um certificado esteja disponível, o certificado pode ser renovado apenas enquanto os registros de validação permanecerem intactos e um cabeçalho Host desmarcado pode rotear uma solicitação para o contexto de locatário errado.

O modelo mais seguro é tratar cada nome de host de marca como um recurso de plano de controle durável. Propriedade, emissão de certificado, substituição de DNS, ativação de roteamento, suspensão e exclusão precisam de estado explícito. No momento da solicitação, o nome do host restringe o contexto de locatário permitido, enquanto a chave API permanece o limite de autorização.

Separe o ciclo de vida do domínio em verificações independentes

Não represente um domínio personalizado com um único booleano, como verified. No mínimo, acompanhe quatro condições independentes:

• Propriedade: O cliente comprovou o controle do nome do host?
• Certificado: Um certificado válido foi emitido e implantado na borda?
• DNS: O DNS autoritativo aponta para o esperado destino do gateway?
• Roteamento: O nome do host exato está vinculado a um locatário ativo e perfil de roteamento?

Essa separação reflete o comportamento documentado do provedor de borda. Os produtos gerenciados com nome de host personalizado podem usar diferentes registros e status para propriedade de nome de host e validação de certificado. Portanto, a resolução de DNS por si só não prova que o endpoint está pronto.

Uma máquina de estados prática é:

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

Estes são estados de negócios, não cópias diretas de status de provedores. Armazene o status bruto do provedor separadamente e, em seguida, derive seu próprio estado de acordo com invariantes documentados. Por exemplo, marque um domínio ready somente quando a propriedade for válida, o certificado estiver ativo, o DNS apontar para o destino esperado e a rota de borda estiver habilitada.

Recomendação: torne as transições monotônicas durante a ativação inicial. Uma investigação TLS transitória e bem-sucedida não deve ignorar a validação de propriedade ou as verificações de roteamento. Após a ativação, a reconciliação pode mover um domínio de ready para suspended ou para um estado degradado explícito quando essas invariantes param de ser mantidas.

Armazenar um domínio como um recurso de primeira classe

Um registro de domínio para um gateway operacional de IA de etiqueta branca API deve conter informações suficientes para recuperação de API chamadas e provedores ambíguos 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"
}

Normalize o nome do host para ASCII minúsculo usando uma biblioteca com reconhecimento de IDNA antes das verificações de exclusividade. Remova um ponto final e rejeite literais de IP, caminhos de URL, portas, curingas, a menos que haja suporte explícito, e nomes fora de sua política de sufixo público aceita. Preserva o formulário de exibição enviado apenas como metadados não-autorizados.

Aplica uma restrição de exclusividade global no nome do host normalizado. Dois locatários nunca devem ser capazes de reivindicar a mesma autoridade, mesmo quando usam letras maiúsculas ou representações Unicode diferentes.

Pré-validar antes de alterar o DNS de produção

Quando a plataforma de borda oferecer suporte, emita e implante o certificado antes de solicitar ao cliente que altere o CNAME de produção.Uma sequência típica é:

1. Crie o recurso de domínio com uma chave de idempotência.
2. Retorne os registros de propriedade e validação de certificado.
3. Pesquise ou receba eventos do provedor até que ambas as validações sejam bem-sucedidas.
4. Confirme se o certificado foi implantado para o nome de host exato.
5. Peça ao cliente para apontar o CNAME de produção para o gateway target.
6. Resolva DNS autoritativo de mais de um local de rede.
7. Ative a rota e execute uma investigação autenticada de ponta a ponta.
8. Marque o domínio ready.

Fato: a documentação de borda SaaS gerenciada descreve sequências de migração com tempo de inatividade zero nas quais a validação e a emissão do certificado ocorre antes das alterações do CNAME de produção. Compensação: isso evita uma lacuna visível de ativação de TLS, mas exige que o cliente crie registros adicionais TXT, CNAME ou de validação delegada.

Se a pré-validação não estiver disponível, exponha explicitamente a provável interrupção. Não prometa tempo de inatividade zero quando a emissão do certificado começar somente após a movimentação do tráfego.

Roteie pela autoridade exata e autorize a chave

A borda confiável deve manter uma lista de permissões exata do nome do host ao locatário permitido ou ao contexto da marca:

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

Rejeite autoridades desconhecidas, inativas e ambíguas. Nunca os envie para um locatário padrão. Para HTTP/1.1, valide Host; para HTTP/2 e HTTP/3, valide :authority. Quando o TLS for encerrado na mesma borda, compare a autoridade da solicitação com o SNI e o contexto do certificado conforme suportado pelo proxy.

O encaminhamento de cabeçalhos exige a mesma disciplina. A borda pública deve remover X-Forwarded-Host, Forwarded de entrada e quaisquer cabeçalhos de locatário internos e, em seguida, adicionar um host canônico e um sinal de locatário resolvido. A origem deve aceitar esses sinais somente em conexões autenticadas de ponta a origem.

A sequência de autorização do tempo de execução deve ser:

1. Resolver a autoridade normalizada por meio da lista de permissões de nome de host ativo.
2. Autenticar a chave API de forma independente.
3. Carregar o identificador de locatário imutável anexado ao key.
4. Verifique se o inquilino da chave é permitido no nome de host resolvido.
5. Aplique modelo, orçamento, limite de taxa e política de roteamento usando IDs de inquilino e chave.
6. Grave registros de uso nesses IDs imutáveis, não no nome do host.

Isso preserva a função do Parceiro API automação sem transformar uma operação de gerenciamento de domínio em um atalho de autorização.

Retorna 421 Misdirected Request quando a autoridade não corresponde à origem configurada ou ao contexto de conexão. Retorna 403 Forbidden quando o nome do host é válido, mas a chave autenticada pertence a um locatário que não tem permissão para usá-la. Mantenha os corpos de erro genéricos o suficiente para que eles não divulguem qual locatário possui um nome de host.

Compatibilidade de endpoint canônico e de marca

Alguns clientes precisam de uma chave para funcionar no endpoint canônico do gateway e em seu endpoint de marca. Isso é aceitável somente quando ambos os nomes de host são resolvidos para o mesmo contexto de locatário autorizado.Vincular estritamente cada chave a um nome de host reduz o uso entre marcas, mas complica as migrações e os clientes que alternam entre endpoints.

Recomendação: o modelo permitiu contextos de endpoint como política de chave em vez de comparar strings dentro do código do aplicativo. Por exemplo, uma chave pode permitir tenant:any-active-hostname, brand:brand_42 ou um domain_id exato.

Expor operações de ciclo de vida por meio do parceiro API

Um mínimo API deve suportar criação, inspeção, revalidar, suspender, retomar e excluir:

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}

As operações de criação e exclusão devem aceitar chaves de idempotência estáveis. APIs do provedor, propagação de DNS e tempos limite de rede podem deixar o chamador sem saber se uma operação foi bem-sucedida. Persista o registro da operação antes de invocar o provedor de borda e retorne o mesmo domínio ou operação de exclusão quando a solicitação for repetida com a mesma chave e carga útil equivalente.

Emita eventos de ciclo de vida assinados, como custom_domain.verification_required, custom_domain.certificate_active, custom_domain.ready, custom_domain.dns_drifted, custom_domain.renewal_at_risk e custom_domain.deleted. Os eventos são notificações, não a única fonte da verdade; os consumidores devem ser capazes de recuperar o estado atual após entrega perdida ou duplicada.

Reconciliar DNS, certificados e roteamento continuamente

A ativação não é o fim do ciclo de vida. Os registros DNS são editados, os registros de validação desaparecem, desvios de configuração de borda e certificados se aproximam da renovação.

Execute um reconciliador periódico que verifica:

• DNS autoritativo e o CNAME esperado ou destino delegado
• Nome do host do provedor e status do certificado
• Nomes, expiração e renovação dos certificados health
• Presença de registros de validação de DNS necessários
• Propriedade exata da rota de borda e estado de ativação
• A elegibilidade atual do locatário para fornecer tráfego

A automação de certificados validados por DNS pode depender da validação dos registros CNAME que permanecem publicamente resolvíveis. Alertar antes da expiração, em vez de presumir que a renovação automática sempre será bem-sucedida.

Use novas tentativas limitadas com espera exponencial e instabilidade para operações de certificado. Preservar a conta ACME e o estado do pedido onde você opera a emissão diretamente. A exclusão e a recriação repetidas podem consumir limites de taxa de pedido de certificado ou de domínio registrado. Os registros de nome de host pendentes também podem consumir a cota do provedor até serem explicitamente removidos.

Previsão operacional: sem reconciliação, as falhas mais comuns aparecerão após uma integração bem-sucedida, durante edições de DNS, renovação de certificados, desvios do lado do provedor ou rotatividade de clientes. Esta é uma expectativa arquitetônica, não uma taxa de falha medida.

Remoção em duas fases

Excluir a linha do banco de dados primeiro não é seguro porque mapeamentos de borda, certificados ou DNS podem sobreviver a isso.Use um fluxo de trabalho auditável de duas fases:

1. Mova o domínio para draining e pare de anunciá-lo para novas integrações.
2. Decida se as solicitações existentes receberão um curto período de carência ou rejeição imediata.
3. Desative a rota de borda para que o nome do host não possa ser resolvido para um locatário padrão.
4. Remova o nome de host personalizado e a associação de certificado do provedor.
5. Peça ao cliente para remover ou substituir o registro DNS.
6. Verifique se o DNS não aponta mais para seu serviço.
7. Marque o recurso deleted enquanto retém identificadores e um registro de auditoria.

Um CNAME pendente direcionado a um serviço desprovisionado pode criar um risco de controle de subdomínio. Por outro lado, deixar um mapeamento obsoleto ativo pode continuar enviando o tráfego de um antigo cliente pela sua borda. Combine a limpeza do provedor e a verificação de DNS na mesma operação de exclusão, mas registre cada resultado de forma independente.

Teste o limite, não apenas o caminho feliz

Antes de ativar domínios de clientes, automatize testes de conformidade para:

• Um cabeçalho Host ou X-Forwarded-Host forjado
• SNI conflitante e autoridade HTTP valores
• Um nome de host desconhecido e um nome de host conhecido, mas suspenso
• Uma chave válida do inquilino A usada no nome de host do inquilino B
• Solicitações de criação e exclusão duplicadas com a mesma chave de idempotência
• O mesmo nome de host enviado com variações de maiúsculas e minúsculas, ponto final ou Unicode
• DNS mudou para longe do destino esperado após ativação
• Um registro de validação de certificado removido antes da renovação
• Exclusão interrompida após o mapeamento de borda ser removido, mas antes das alterações de DNS

Verifique também se os registros, o faturamento, a atribuição de uso, os limites de taxa e as decisões de política usam IDs de locatário e chave. Nomes de host são entradas mutáveis ​​de apresentação e roteamento; eles não devem se tornar identidades financeiras ou de segurança.

Lista de verificação de implementação

• Normalizar nomes de host e impor exclusividade global.
• Rastrear propriedade, certificado, DNS e prontidão de rota separadamente.
• Pré-validar certificados antes da transição, quando compatível.
• Permitir listar autoridades exatas no borda confiável.
• Retire cabeçalhos de encaminhamento não confiáveis e crie um sinal de origem autenticado.
• Autorize a chave API no contexto do locatário do nome do host.
• Use 421 para origem ou incompatibilidade de conexão e 403 para uso de chave entre locatários.
• Faça criar e excluir idempotente.
• Reconcilie continuamente o estado do provedor, o DNS, o roteamento e a integridade da renovação.
• Exclua explicitamente os mapeamentos de borda e verifique o DNS durante a desativação.

Um endpoint de marca estará pronto somente quando o estado do plano de controle e o comportamento do plano de dados concordarem.Modele esse contrato explicitamente, teste os caminhos negativos e mantenha a chave API como o limite final de autorização do locatário.

Leitura relacionada

• operações do parceiro idempotente API