Em 29 de agosto de 2026, a OpenAI marcou como geralmente disponíveis (GA) dois recursos de segurança para a API: Mutual TLS (mTLS) e federação de identidade de workload com X.509. Eles se complementam, mas não são a mesma coisa. O mTLS acrescenta a verificação de um certificado de cliente à autenticação normal da API. Já a federação X.509 permite trocar uma identidade comprovada por certificado por um token de acesso de curta duração, substituindo a chave de API — sem eliminar a exigência do certificado nas chamadas protegidas.
Para equipes que querem adotar o recurso sem transformar uma mudança de segurança em indisponibilidade, o ponto mais importante é o escopo: o certificado de confiança pode ser ativado por projeto ou para a organização. O caminho mais seguro é começar em um projeto não crítico, validar os workloads e só depois ampliar o escopo.
O que mudou com o GA de 29 de agosto de 2026
As release notes da OpenAI registram, em 29 de agosto de 2026, que mTLS e federação X.509 passaram a GA para a OpenAI API. A documentação atual de desenvolvedores também já apresenta os dois fluxos como recursos disponíveis da API e detalha configuração, escopo, rotação e autenticação.
Há, porém, uma divergência documental que merece atenção: uma página do Help Center sobre o “programa beta” de Mutual TLS ainda informa que o recurso está em beta, apesar de ter sido atualizada poucos dias antes do anúncio de GA. Isso entra em conflito com as release notes datadas e com a documentação atual de desenvolvedores. Para decisões de implantação, a referência mais consistente hoje é combinar o anúncio de GA com os guias atuais de Mutual TLS e de federação X.509, rechecando o estado do produto antes de uma mudança de produção.
Antes de ativar: permissões, certificados e plano de retorno
A OpenAI usa controle de acesso baseado em função para administrar mTLS. A permissão api.mtls.read permite listar, visualizar e testar as configurações de certificado. A permissão api.mtls.write permite fazer upload, atualizar, ativar, desativar e excluir certificados. O papel de proprietário da organização inclui essas permissões, e elas também podem ser concedidas por uma função personalizada.
Antes de ativar qualquer certificado, prepare quatro itens:
- um certificado de cliente e sua chave privada para cada workload;
- os certificados intermediários necessários para formar a cadeia de confiança;
- uma âncora de confiança estável, codificada em PEM, que possa ser ativada no nível de projeto ou organização;
- um projeto não crítico e um caminho de recuperação já testado para o caso de a política bloquear tráfego válido.
As chaves privadas devem ficar fora do controle de versão e de logs. O mesmo cuidado vale para conteúdo de certificados e credenciais bearer.
Como ativar mTLS por projeto
O detalhe operacional que mais evita surpresa é simples: fazer upload não ativa mTLS. O upload apenas armazena o certificado de confiança. A mudança de comportamento ocorre quando ele é ativado em um projeto ou na organização.
- Acesse Organization settings > Security > Mutual TLS na plataforma.
- Faça upload de uma âncora de confiança em PEM por objeto de certificado e use um nome que ajude a identificar a autoridade e a geração de rotação.
- Se necessário, adicione um filtro CEL para restringir quais certificados de cliente verificados podem ser aceitos por aquela âncora.
- Ative o certificado primeiro em um projeto não crítico.
- Altere os workloads desse projeto para usar um host mTLS e envie requisições representativas de todos os clientes esperados.
- Depois da validação, ative o mesmo certificado nos outros projetos planejados ou no nível da organização.
A administração também pode ser automatizada pela API:
| Ação | Endpoint |
|---|---|
| Fazer upload de certificado | POST /v1/organization/certificates |
| Listar certificados da organização | GET /v1/organization/certificates |
| Consultar, atualizar ou excluir um certificado | GET, POST ou DELETE /v1/organization/certificates/{certificate_id} |
| Ativar ou desativar para a organização | POST /v1/organization/certificates/activate ou /deactivate |
| Listar, ativar ou desativar em projeto | GET ou POST /v1/organization/projects/{project_id}/certificates |
Essas operações exigem a credencial administrativa com a permissão de leitura ou escrita correspondente.
Projeto ou organização: como o escopo é aplicado
O escopo define onde o certificado passa a ser obrigatório. A documentação atual diz que a OpenAI verifica certificados ativos no nível de projeto antes dos certificados ativos no nível de organização. Se nenhum dos dois escopos tiver certificado ativo, o mTLS não acrescenta uma verificação de certificado à requisição.
Na prática, ativar por projeto é a melhor opção para rollout gradual: você consegue testar um serviço, uma equipe ou um ambiente sem impor imediatamente a mesma política a todos os projetos. Ativar no nível da organização é mais abrangente e deve ser feito somente quando os workloads afetados já estiverem preparados para apresentar certificados aceitos.
Esse desenho também ajuda na rotação e no isolamento de incidentes. Um projeto pode adotar uma nova âncora de confiança antes dos demais, enquanto a organização mantém outro certificado ativo durante a transição.
Requisitos do certificado e da cadeia X.509
A configuração aceita uma âncora de confiança em PEM por objeto de certificado. O certificado enviado precisa ser válido e expirar mais de um dia depois do upload. Para a verificação de requisições, o certificado do cliente precisa incluir um Authority Key Identifier (AKI).
Uma requisição protegida por mTLS só passa quando:
- o certificado do cliente está válido no momento da requisição e é apropriado para autenticação TLS de cliente;
- a cadeia do cliente chega a uma âncora de confiança ativa no projeto ou na organização;
- todos os intermediários necessários são apresentados pelo cliente durante o handshake TLS;
- a cadeia passa pela validação X.509 padrão e, quando houver, pelo filtro CEL associado.
A OpenAI informa que não busca intermediários ausentes em URLs AIA e não executa verificações CRL ou OCSP nesse fluxo. Portanto, o cliente precisa apresentar a cadeia completa exigida, e a resposta a incidentes deve depender de rotação, desativação e controles próprios de ciclo de vida de certificados.
Também é possível adicionar filtros CEL com atributos do subject e dos Subject Alternative Names. Isso permite, por exemplo, aceitar somente certificados de uma unidade organizacional específica ou de um namespace DNS esperado.
Como chamar a API depois da ativação
Depois que o mTLS é ativado para o escopo, o tráfego deve ir para um host mTLS. Os hosts documentados são:
- mtls.api.openai.com — host mTLS padrão;
- mtls-us.api.openai.com — host regional dos Estados Unidos;
- mtls-eu.api.openai.com — host regional da União Europeia.
O caminho /v1 permanece o mesmo da superfície de API correspondente, mas a OpenAI recomenda testar cada API e modelo usado pelo workload, porque disponibilidade de rotas e modelos pode variar entre hosts regionais.
O mTLS não substitui a autenticação bearer normal. Em um teste com curl, por exemplo, a chamada deve enviar a cadeia do cliente com --cert, a chave privada com --key e continuar enviando o cabeçalho Authorization: Bearer .... O arquivo de cadeia deve começar pelo certificado do cliente e depois incluir os intermediários necessários.
Quando usar federação de identidade X.509
A federação de identidade de workload com X.509 resolve um problema diferente: eliminar uma chave de API de longa duração do workload. O fluxo usa o mesmo trust store do mTLS, mas acrescenta um provedor de identidade X.509 e um mapeamento para uma conta de serviço em um projeto.
- A organização envia e ativa a raiz confiável nas configurações de Mutual TLS.
- Um provedor X.509 deriva atributos openai.* do certificado verificado e precisa produzir um openai.subject não vazio.
- Um mapeamento associa essa identidade a uma conta de serviço dentro de um projeto e às permissões de API estritamente necessárias.
- O workload apresenta o certificado ao endpoint POST https://mtls.auth.openai.com/oauth/token e recebe um bearer token de curta duração.
- O workload chama a API em um host mTLS enviando tanto o token quanto um certificado aceito.
O token substitui a chave de API, mas não substitui o certificado. O token expira em no máximo uma hora e nunca dura mais que o certificado verificado. Não há refresh token: o workload repete a troca X.509 para obter um novo token.
A documentação atual também diz que esse fluxo X.509 é para a OpenAI API e não é suportado pelo Codex; no Codex, a orientação é usar OIDC ou SPIFFE JWT-SVID conforme o guia de workload identity correspondente.
Rotação, erros e limitações que devem entrar no runbook
A rotação deve ser feita com sobreposição. Primeiro faça upload da nova âncora sem desativar a anterior, ative-a nos escopos desejados, migre os workloads e teste. Só depois desative e, por fim, exclua o certificado antigo. Intermediários podem ser rotacionados sem trocar a raiz configurada, desde que a cadeia completa atualizada seja apresentada nas novas conexões.
| Código | O que verificar |
|---|---|
| certificate_required | Há certificado ativo no escopo, mas a requisição não apresentou material de certificado de cliente. |
| invalid_certificate | O certificado não pôde ser lido ou está sem o AKI exigido. |
| certificate_verification_failed | A cadeia apresentada não alcança uma âncora de confiança ativa. |
| certificate_attribute_verification_failed | A cadeia verificou, mas o filtro CEL rejeitou o certificado. |
| authentication_temporarily_unavailable | Erro temporário do verificador ou avaliador CEL; trate como falha transitória e aplique a política normal de retry. |
Entre as limitações documentadas estão o máximo de 50 objetos de certificado por organização, a ausência de CRL/OCSP, a incompatibilidade entre mTLS e Private Link e o fato de que mTLS não fornece autorização somente por certificado. A autenticação bearer continua necessária — por chave de API tradicional ou pelo token curto da federação X.509.
Checklist para uma implantação sem bloquear produção
- Confirme que o administrador tem api.mtls.read e, para mudanças, api.mtls.write.
- Cadastre a âncora de confiança e valide data de expiração, AKI e cadeia completa.
- Comece por um projeto não crítico e tenha um caminho de rollback testado.
- Faça o workload usar o host mTLS correto e mantenha o bearer credential exigido.
- Teste todos os modelos, rotas, regiões e clientes que realmente serão usados.
- Use filtros CEL apenas depois de validar que os atributos do certificado são estáveis e previsíveis.
- Planeje rotação com sobreposição e mantenha a chave privada fora de repositórios e logs.
- Se quiser remover chaves de API longas, configure a federação X.509 com conta de serviço e mapeamento por projeto.
- Antes de uma mudança ampla, reconfirme as release notes e os guias atuais, especialmente enquanto a página antiga do Help Center ainda mantiver a etiqueta de beta.
O ganho do GA é menos “um botão novo” e mais a possibilidade de tratar identidade de workload e transporte mTLS como controles operacionais de produção. A ativação por projeto dá uma forma prática de reduzir o raio de impacto: validar primeiro, ampliar depois e separar claramente quem administra certificados de quem apenas consome a API.
