Resumo
Acesso
Os endpoints do EKM podem ser acessados pela API de Gerenciamento usando uma chave de API administrativa. https://platform.openai.com/settings/organization/admin-keys Não use uma chave de API comum. As chaves de API administrativas estão disponíveis apenas para proprietários da organização.
Use
api.external_keys.writepara criar ou excluir chaves externas eapi.external_keys.readpara listar, recuperar ou validar chaves externas. Uma única chave só precisa de ambos os escopos se tiver que executar operações de leitura e gravação.
Uso
Sua configuração de EKM é registrada no nível da organização por meio de um novo endpoint: https://api.openai.com/v1/organization/external_keys.
O registro da configuração de EKM retorna um external_key_id no formato extkey_xxxx.
A configuração de EKM é ativada no nível do projeto quando você informa um external_key_id no corpo da solicitação ao endpoint existente de criação de projetos: https://api.openai.com/v1/organization/projects.
Restrições
Primeiro, você deve testar o EKM em um novo projeto por meio da API de Gerenciamento.
Recomendamos a criação de novos projetos para suas cargas de trabalho do EKM. Observe as seguintes boas práticas antes de implementar o EKM em seus projetos de produção existentes.
Teste primeiro todos os recursos da API utilizados em produção no seu projeto de API EKM de teste.
Implemente a solução gradualmente, em vez de ativar o EKM em todos os projetos de API de produção de uma só vez.
Endpoint no nível da organização
Registre uma chave externa em sua organização.
AWS
Exemplo de solicitação:
tipo: string - Sempre "aws"
nome: string - Um nome amigável para sua configuração
role_arn: string - O ARN da função que a OpenAI assumirá em sua nuvem.
kms_arn: string - O ARN do Sistema de Gerenciamento de Chaves para a chave mestra que você gerencia.
external_id: string - O ID da sua organização ou o ID do seu projeto de API
curl -X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys" \
-d '{
"type": "aws",
"name": "AWS EKM Config",
"role_arn": "arn:aws:iam::<12_DIGIT_ACCOUNT_NUMBER>:role/<ROLE>",
"kms_arn": "arn:aws:kms:<REGION>:<ACCOUNT_NUMBER>:key/<UUID>",
"external_id": "<your org id or project id>"
}'Exemplo de resposta:
{
"id": "extkey_xxxx",
"object": "organization.external_key",
"created_at": 1746175499,
"api_project_ids": [],
"type": "aws",
"name": "AWS EKM Config",
"role_arn": "arn:aws:iam::<ACCOUNT_NUMBER>:role/<ROLE>",
"kms_arn": "arn:aws:kms:<REGION>:<ACCOUNT_NUMBER>:key/<UUID>",
"external_id": "<your org id or project id>"
}GCP
Exemplo de solicitação:
tipo: string - Sempre "gcp",
nome: string - Um nome amigável para sua configuração
workload_identity_project_number: string - Número do projeto do GCP, em formato numérico, no qual você registrou a identidade de carga de trabalho da OpenAI.
workload_identity_pool_id: string - O pool que contém o provedor de identidade de carga de trabalho que você registrou para a OpenAI.
workload_identity_provider_id: string - O provedor de identidade de carga de trabalho que você regisOpenAItrou para a OpenAI
público-alvo: string - O público-alvo que a OpenAI deve passar no token quando assumirmos uma função por meio do seu GCP STS.
kms_project_id: string - O nome do projeto GCP onde seu KMS está hospedado
kms_key_ring_name: string - O chaveiro do Sistema de Gerenciamento de Chaves que contém a chave mestra que você gerencia.
kms_key_name: string - O nome da chave mestra do Sistema de Gerenciamento de Chaves
kms_key_location: string - A região onde sua chave mestra do Sistema de Gerenciamento de Chaves está localizada.
Se o KMS estiver em um projeto do GCP diferente daquele em que você registrou a identidade de carga de trabalho da OpenAI, verifique se o KMS está ativado no projeto que contém essa identidade. Para isso, acesse https://console.developers.google.com/apis/api/cloudkms.googleapis.com/overview.
curl -X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys" \
-d '{
"type": "gcp",
"name": "GCP EKM Config",
"workload_identity_project_number": "123456789012",
"workload_identity_pool_id": "openai-azure",
"workload_identity_provider_id": "openai-ekm-service-role",
"audience": "<your org id or project id>",
"kms_project_id": "adjective-noun-12345",
"kms_key_name": "openai-kms-key",
"kms_key_ring_name": "openai-kms-key-ring",
"kms_key_location": "us-east1"
}'Exemplo de resposta:
{
"id": "extkey_xxxxxx",
"object": "organization.external_key",
"created_at": 1746174349,
"api_project_ids": [],
"type": "gcp",
"name": "GCP EKM Config",
"workload_identity_project_number": "123456789012",
"kms_key_ring_name": "openai-kms-key-ring",
"kms_key_name": "openai-kms-key",
"kms_key_location": "us-east1",
"audience": "<your org id or project id>",
"kms_project_id": "adjective-noun-12345",
"workload_identity_pool_id": "openai-azure",
"workload_identity_provider_id": "openai-ekm-service-role"
}Azure
Exemplo de solicitação:
tipo: string - Sempre "azure",
nome: string - Um nome amigável para sua configuração
tenant_id: string - O UUID do seu locatário do Azure
vault_uri: string - O URI do cofre do Azure que contém a chave mestra que você gerencia.
key_name: string - O nome da chave mestra do Azure Key Vault que você gerencia.
Deve ter o formato <org-xxx>--<any_name>
onde org-xxx é o seu ID de organização OpenAI, que você pode encontrar em https://platform.openai.com/settings/organization/general
curl -X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys" \
-d '{
"type": "azure",
"name": "Azure EKM Config",
"tenant_id": "<UUID>",
"vault_uri": "https://<VAULT_NAME>.vault.azure.net/",
"key_name": "org-xxx--some-key"
}'Exemplo de resposta:
{
"id": "extkey_xxxx",
"object": "organization.external_key",
"created_at": 1746174377,
"api_project_ids": [],
"type": "azure",
"name": "Azure EKM Config",
"tenant_id": "<UUID>",
"vault_uri": "https://<VAULT_NAME>.vault.azure.net/",
"key_name": "org-xxx--some-key"
}OCI
Configure uma chave AES-256 habilitada e conceda à OpenAI acesso a ela. A chave deve ter uma tag de formato livre chamada openai_organization_id, definida como o ID da organização da OpenAI. Para ver as etapas de configuração, consulte: Como configurar o OCI Vault para o gerenciamento de chaves empresariais.
Exemplo de solicitação:
type: string - sempre "oci"
purpose: string - "ekm"; valor padrão quando omitido
nome: string - Um nome amigável para sua configuração
region: string - região da OCI que contém seu cofre e sua chave
vault_ocid: string - OCID completo do seu cofre
key_ocid: string - OCID completo da sua chave AES-256
Não informe key_version_ocid para EKM.
curl -X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys" \
-d '{
"type": "oci",
"purpose": "ekm",
"name": "OCI EKM Config",
"region": "us-ashburn-1",
"vault_ocid": "<VAULT_OCID>",
"key_ocid": "<AES_KEY_OCID>"
}'Exemplo de resposta:
{
"id": "extkey_xxxx",
"object": "organization.external_key",
"created_at": 1746175499,
"api_project_ids": [],
"type": "oci",
"purpose": "ekm",
"name": "OCI EKM Config",
"region": "us-ashburn-1",
"vault_ocid": "<VAULT_OCID>",
"key_ocid": "<AES_KEY_OCID>"
}Em caso de sucesso, a API retorna o código HTTP 200. Salve o ID retornado e use-o como external_key_id ao criar um projeto. As operações existentes de listagem, consulta, validação e exclusão também se aplicam aos registros OCI.
Para a recuperação de PSP, use um registro separado com uma chave RSA-3072, finalidade "psp_decryption" e um key_version_ocid exato. Defina psp_decryption_key_id como o ID do registro da OpenAI. A OpenAI precisa apenas de acesso de leitura aos metadados e às chaves públicas dessa chave RSA. Para ver as instruções completas de configuração, consulte: Configurar chaves assimétricas — OCI Vault.
Exclua uma chave externa registrada em sua organização.
Observação: a exclusão é bloqueada enquanto um projeto ativo ou espaço de trabalho usar o registro. Para EKM, arquive primeiro os projetos de API associados. Um registro EKM associado a um espaço de trabalho permanece protegido. Para a recuperação de PSP, substitua ou limpe psp_decryption_key_id em cada projeto ativo que faça referência ao registro antes de excluí-lo. A exclusão de um registro da OpenAI não exclui a chave na nuvem.
Exemplo de solicitação
curl -X DELETE \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys/extkey_xxxx"Exemplo de resposta
{
"id": "extkey_xxxxx",
"object": "organization.external_key.deleted",
"created_at": 1746127808,
"api_project_ids": [],
"type": "aws",
"account_number": "123456789012",
"kms_arn": "arn:aws:kms:<REGION>:<ACCOUNT_NUMBER>:key/<UUID>",
"name": "AWS EKM Config",
"role_arn": "arn:aws:iam::<ACCOUNT_NUMBER>:role/<ROLE>"
}Obtenha as chaves externas registradas em sua organização.
Sem um filtro de finalidade, a lista inclui registros de recuperação de EKM e PSP. Use ?purpose=ekm ou ?purpose=psp_decryption para filtrar os registros por finalidade.
Exemplo de solicitação
curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys"Exemplo de resposta
{
"object": "list",
"data": [
{
"id": "extkey_xxxx",
"object": "organization.external_key",
"created_at": 1746127808,
"api_project_ids": [],
"type": "aws",
"name": "AWS EKM Config",
"account_number": "123456789012",
"kms_arn": "arn:aws:kms:<REGION>:<ACCOUNT_NUMBER>:key/<UUID>",
"role_arn": "arn:aws:iam::<ACCOUNT_NUMBER>:role/<ROLE>"
}
],
"first_id": "extkey_xxxx",
"has_more": false,
"last_id": "extkey_xxxx"
}Validar uma chave externa
Use a validação para verificar se a OpenAI ainda consegue acessar sua chave na nuvem.
Para EKM, a OpenAI verifica se consegue criptografar e descriptografar dados com a chave. Para saber mais sobre o comportamento de revogação e cache, consulte as orientações sobre o ciclo de vida da chave.
Para a recuperação de PSP, a OpenAI recupera a chave pública da versão registrada e a compara com o snapshot armazenado. Uma validação bem-sucedida não confirma que sua identidade de recuperação consegue descriptografar dados. Uma validação malsucedida não remove nem substitui o snapshot armazenado da chave pública.
A recuperação de um registro por meio de GET retorna a configuração armazenada, mas não verifica novamente o acesso à sua chave na nuvem.
Exemplo de solicitação
curl -X POST -H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys/extkey_xxx/validate"Exemplo de resposta
{
"status": "success"
}Ou então, surgiu um erro por parte do provedor de nuvem.
Endpoint no nível do projeto
Crie um novo projeto com um ID de chave externa.
Este endpoint é idêntico ao endpoint "Criar Projeto" existente, com a adição do parâmetro external_key_id na requisição e na resposta.
Exemplo de solicitação
curl -X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/projects" \
-d '{
"name": "Some Project",
"external_key_id": "extkey_xxxx"
}'Exemplo de resposta
{
"object": "organization.project",
"id": "proj_xxxxx",
"name": "Some Project",
"external_key_id": "extkey_xxxx",
"created_at": 1740012721,
"archived_at": null,
"status": "active"
}Atualizar um projeto existente com um ID de chave externa
Este endpoint é idêntico ao endpoint de atualização de projeto existente, com a adição do parâmetro external_key_id na solicitação e na resposta.
Recomendamos a criação de novos projetos de API para suas cargas de trabalho do EKM. Observe as seguintes boas práticas antes de implementar o EKM em seus projetos de produção existentes.
Teste primeiro todos os recursos da API utilizados em produção no seu projeto de API EKM de teste.
Implemente a solução gradualmente, em vez de ativar o EKM em todos os projetos de API de produção de uma só vez.
Exemplo de solicitação
curl -X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/projects/proj_xxx" \
-d '{
"external_key_id": "extkey_xxxx"
}'Liste todos os projetos da sua organização.
Esse endpoint é idêntico ao endpoint existente, mas inclui o campo external_key_id na resposta da API.
Exemplo de solicitação
curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/projects"Exemplo de resposta
{
"object": "list",
"data": [
{
"object": "organization.project",
"id": "proj_xxxx",
"name": "Project Name",
"external_key_id": "extkey_xxxx",
"created_at": 1717798982,
"archived_at": null,
"status": "active"
}
],
"first_id": "proj_xxxx",
"last_id": "proj_xxxx",
"has_more": true
}