Domínios e TLS

Todo tráfego público passa pela borda da plataforma (gateway com WAF → aplicação): o WAF roda dentro do próprio gateway, sem um salto a mais. Você publica rotas pelo portal e a plataforma gera e aplica a configuração; ninguém administra o gateway diretamente.

Hostname padrão

Cada aplicação publicada recebe um hostname único sob o domínio de aplicações da plataforma, no formato <aplicação>-<ambiente>-<organização>.<domínio de aplicações>. Ele não precisa de verificação.

Subdomínio gratuito

Cada projeto pode reservar um subdomínio gratuito num domínio-base da plataforma, por exemplo materia-escura.<domínio-base>. Ele não exige registro no seu DNS nem verificação: nasce ativo e já com TLS, servido pelo certificado curinga do domínio-base (o portal mostra a validade desse certificado).

1. Na aba Domínios do projeto, no cartão Subdomínio gratuito, digite o rótulo e escolha o domínio-base. O portal confere a disponibilidade enquanto você digita e mostra o endereço completo.
2. Confirme. O endereço passa a aparecer como host em Nova rota.

Regras do rótulo: de 3 a 40 caracteres, letras minúsculas, números e hífens, sem hífen no início ou no fim e sem -- nas posições 3 e 4. Nomes da plataforma e endereços de serviço (www, api, admin, status, docs, mail e outros) são reservados. A consulta de disponibilidade nunca revela quem usa um rótulo.

Owner, Admin e Developer reservam, trocam e liberam; Viewer só vê o endereço e o estado. Ao trocar ou liberar, o portal lista as rotas que usam o endereço anterior: elas são removidas e o endereço anterior fica em quarentena por 30 dias, sem poder ser reservado por nenhum projeto (nem pelo mesmo). Se a organização ou o projeto for suspenso, o subdomínio deixa de servir tráfego, mas continua reservado.

Subdomínios de um domínio-base nunca podem ser cadastrados como domínio próprio.

Domínio próprio

1. Em Domínios do projeto, cadastre o domínio (por exemplo, app.exemplo.com.br). Precisa ser um nome completo e fora do domínio da plataforma; um curinga (*.exemplo.com.br) segue as regras de Domínio curinga. Owner, Admin e Developer podem cadastrar.
2. O domínio entra em PENDING_VERIFICATION e o portal mostra um token exclusivo para um registro DNS TXT.
3. Crie o registro no seu provedor de DNS e clique em Verificar. A plataforma também verifica periodicamente.
4. Verificado, o domínio passa a VERIFIED. Se a verificação não der certo em 72 horas, ele passa a FAILED.

Um domínio fica VERIFIED em no máximo uma organização. Se duas organizações cadastrarem o mesmo domínio, fica com ele a primeira que verificar.

Apontar o domínio para a plataforma (CNAME)

Cada organização tem um alvo de borda próprio, no formato <organização>.edge.<domínio da plataforma>, que o portal mostra junto de cada domínio próprio. Aponte o domínio para esse alvo com um registro CNAME:

Tipo	Nome	Valor	TTL
CNAME	app.exemplo.com.br	acme.edge.<domínio da plataforma>	o do seu provedor

• O alvo tem TTL de 60 segundos. Por isso a plataforma consegue mover o tráfego da sua organização (mitigação de ataques, troca de região ou de plano) sem você mudar nada no seu DNS.
• Domínio raiz (exemplo.com.br, sem subdomínio): o DNS não permite CNAME no apex. Use o registro ALIAS/ANAME ou o CNAME flattening do seu provedor apontando para o mesmo alvo. Se o provedor não oferecer nenhum dos dois, o portal mostra um par de IPs fixos para registros A, com um aviso: com IP fixo, a plataforma não consegue mover o seu tráfego sem você alterar o DNS.
• Checagem de apontamento: ao verificar o domínio, e periodicamente depois, a plataforma confere para onde ele aponta. O CNAME para o alvo da sua organização confirma o apontamento. Um CNAME para o alvo de outra organização é recusado e o domínio não fica ativo até ser corrigido. Sem CNAME (apex com ALIAS ou IPs fixos), o apontamento fica como não confirmado, sem bloquear o domínio.
• Um domínio curinga (*.exemplo.com.br) aponta da mesma forma: *.exemplo.com.br CNAME para o alvo.

Certificado TLS

A plataforma emite ou associa o certificado TLS somente para domínios VERIFIED. O portal mostra o status e a validade do certificado. A chave privada nunca é exibida nem devolvida pela API.

Por padrão o certificado é automático: a plataforma emite e renova sozinha.

Certificado próprio e domínio curinga

Certificado próprio

Quando você precisa de um certificado OV/EV, de uma autoridade certificadora contratada, de um registro CAA que só autoriza a CA da empresa ou de um curinga, envie o seu certificado na seção Certificado do domínio. Só Owner e Admin enviam; o recurso depende do plano.

• Formato: PEM. Certificado, cadeia intermediária (opcional se já vier junto do certificado) e chave privada sem senha (PKCS#1, PKCS#8 ou SEC1).
• Chave: RSA de 2048 a 4096 bits ou ECDSA P-256/P-384.
• Validações: a chave precisa corresponder ao certificado; o certificado não pode ser de autoridade certificadora; com uso estendido (EKU), precisa permitir autenticação de servidor; precisa estar válido por pelo menos 7 dias; os nomes alternativos (SAN) precisam cobrir o domínio (o exato, ou um curinga de um nível que o cubra); a cadeia precisa chegar a uma CA pública confiável sem baixar intermediários. Certificado e cadeia até 32 KB, chave até 8 KB. Cada erro aparece no campo correspondente.
• Guarda: certificado e chave vão para o cofre da plataforma; o banco guarda só emissor, nomes, validade e impressão digital. A chave nunca volta pela API nem aparece em logs.
• Troca: um novo envio substitui o anterior sem derrubar conexões. Voltar ao automático remove o certificado próprio de um domínio exato.
• Avisos: o portal avisa a 30, 14 e 7 dias do vencimento, e os donos e administradores da organização recebem e-mail. Num domínio exato com Voltar ao certificado automático quando vencer (padrão), o domínio volta ao certificado automático quando o seu vence; sem essa opção, o certificado vencido continua servido até você enviar outro.

Domínio curinga

Um domínio curinga (*.exemplo.com.br) publica qualquer host de um nível sob ele (api.exemplo.com.br, loja.exemplo.com.br) sem nova verificação.

• O * precisa ser o primeiro e único curinga, e a base não pode ser um sufixo público: *.com.br e *.github.io são recusados.
• A verificação usa o TXT na base: _atlas-challenge.exemplo.com.br.
• Um curinga verificado por uma organização impede outra de verificar o mesmo curinga ou qualquer host coberto por ele, e um host já verificado por outra organização impede o curinga que o cobriria. Dentro da mesma organização, curinga e domínio exato convivem; o exato tem precedência no roteamento.
• Por que exige certificado próprio: emitir um certificado curinga exige provar o controle da zona DNS (desafio DNS-01), e a plataforma não tem acesso ao seu DNS. O domínio fica VERIFIED com o certificado pendente, e nada é publicado até você enviar o certificado.
• Hosts de dois níveis (a.b.exemplo.com.br) não são aceitos, porque o certificado curinga cobre um nível só.

Autenticação mútua (mTLS)

Integrações B2B e Open Finance costumam exigir que o cliente também apresente um certificado. Num domínio próprio verificado, Owner e Admin do projeto ligam o mTLS na seção Certificado do cliente (mTLS) do detalhe do domínio, se o plano incluir o recurso (Business e Enterprise). O hostname padrão e o subdomínio gratuito não aceitam mTLS.

Modo	Comportamento
Off	Padrão. A borda não pede certificado ao cliente.
Optional	A borda pede e valida o certificado quando o cliente envia; sem certificado, a requisição passa.
Required	Sem um certificado emitido por uma das CAs cadastradas, o handshake TLS falha e a aplicação não recebe a requisição.

Bundle de CA: envie em PEM (-----BEGIN CERTIFICATE-----), até 64 KiB, só com certificados de CA (com CA:TRUE) dentro da validade. Certificado folha, CA vencida, chave privada no arquivo ou bundle acima do limite são recusados. O portal mostra o fingerprint SHA-256 do bundle e a validade da CA que vence primeiro; a auditoria registra só o fingerprint, nunca o conteúdo.

Revogação (opcional): uma CRL em PEM (-----BEGIN X509 CRL-----), aplicada pela borda; a URL da CRL e o OCSP ficam registrados na configuração do domínio.

Cabeçalhos repassados à aplicação quando a borda valida o certificado:

Cabeçalho	Conteúdo
X-Client-Cert-Subject	Subject do certificado do cliente
X-Client-Cert-SAN	SAN (URI) do certificado
X-Client-Cert-Fingerprint	Fingerprint SHA-256 do certificado
X-Client-Cert-Verified	true no modo Required

A borda remove esses cabeçalhos quando eles vêm do cliente, em qualquer modo e em qualquer host: um X-Client-Cert-Verified: true forjado nunca chega à aplicação. No modo Optional, a presença de X-Client-Cert-Fingerprint indica que um certificado válido foi apresentado.

Exemplo de chamada com certificado de cliente:

curl --cert cliente.crt --key cliente.key https://api.exemplo.com.br/saldo

Sem --cert, no modo Required, o curl termina com erro de handshake TLS.

Rotas

Uma rota liga um host (domínio verificado, hostname padrão ou subdomínio gratuito do projeto) e um prefixo de path a uma aplicação do mesmo projeto.

• Não pode haver duas rotas com o mesmo host e o mesmo prefixo.
• Toda rota tem rate limit por IP de origem, em requisições por minuto. Se você não informar, vale o padrão do plano; valores acima do teto do plano são recusados. Os números estão em Planos, recursos e limites.
• O portal mostra host, path, destino, rate limit e se a rota já foi aplicada no gateway.
• Caminhos internos (/_internal, /admin-api, /metrics) e arquivos sensíveis publicados por engano (/.git/, /.env, /.htpasswd, cópias .bak, ~, .swp, .orig e semelhantes) respondem 404 em qualquer rota. /.well-known/ continua liberado.

Cada mudança gera uma revisão numerada e validada da configuração do gateway antes de ser aplicada. As rotas da plataforma e as dos clientes ficam em grupos separados.

Remover um domínio

Owner e Admin removem domínios. As rotas que usam o domínio são despublicadas na mesma operação, e o certificado automático do domínio é apagado junto com a chave privada.

Limites

O número de domínios próprios depende do plano. Serviços TCP que não são HTTP e HTTP/3 ainda não são suportados.