OpenAI

EKM (Chaves Externas) na API de Gerenciamento

Gerencie chaves externas para EKM usando a API de Gerenciamento.

Atualizado: 14 days ago

Resumo

Acesso

  • Os endpoints do EKM são acessíveis na API de Gerenciamento por meio de uma chave de API de administrador. https://platform.openai.com/settings/organization/admin-keys (não use uma chave de API normal). As chaves da API de administrador estão disponíveis para os proprietários da organização.

  • Use api.external_keys.write para criar ou excluir chaves externas e api.external_keys.read para listar ou validar chaves externas. Uma única chave só precisa de ambos os escopos se tiver que executar operações de leitura e gravação.

  • No momento, precisamos adicionar a sua organização como um recurso obrigatório nesses endpoints. Você saberá que possui o recurso ativado se vir **external_key_id** retornado do endpoint List Projects existente: https://api.openai.com/v1/organization/projects

Uso

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. No entanto, se você deseja o EKM em um projeto existente, podemos adicioná-lo à lista de recursos prioritários. 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 que você usa em produção no seu projeto de API EKM de teste.

    • Implemente uma implantação gradual em vez de preencher 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": "Configuração do AWS EKM",
  "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 - O número do projeto GCP de 12 dígitos onde 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 seu KMS estiver em um projeto do GCP diferente daquele em que você registrou a Identidade de Carga de Trabalho da OpenAI, certifique-se de que o projeto que contém a Identidade de Carga de Trabalho da OpenAI tenha o KMS habilitado, acessando 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 "azul",

  • 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. 

curl -X POST \
 -H "Content-type: application/json" \
 -H "Autorização: Portador $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"
}

Exclua uma chave externa registrada em sua organização.

Observação: você só pode excluir uma chave externa se ela não estiver associada a nenhum projeto ativo. Se estiver associado a um projeto ativo, você deve arquivar esse projeto primeiro.

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.

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": "Configuração AWS EKM",
      "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

Você pode usar este endpoint para verificar várias coisas.

  • Sua configuração de nuvem externa permanece válida com a OpenAI após as alterações (você verá uma resposta de sucesso).

  • A revogação da sua chave foi realizada corretamente, está sendo processada pela OpenAI e entrará em vigor após o término do tempo de vida (TTL) do cache de 1 hora (você verá uma mensagem de erro).

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": "project",
  "id": "proj_xxxxx",
  "title": "Some Project",
  "external_key_id": "extkey_xxxxx",
  "created": 1740012721,
  "organization_id": "org-xxxxx",
  "is_initial": false,
  "geography": null,
  "scale_tier_enabled": false,
  "disable_user_api_keys": false,
  "zdr_type": null,
}

[Restrito] 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. Se você deseja usar o EKM em todos os seus projetos de API existentes, solicite ao seu gerente de contas e nós o adicionaremos à lista de recursos. 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 que você usa em produção no seu projeto de API EKM de teste.

  • Implemente uma implantação gradual em vez de preencher 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 "Autorização: Portador $TOKEN" \
 "https://api.openai.com/v1/organization/projects/proj_xxx" \
-d '{
   "external_key_id": "extkey_xxxx"
}'

Liste todos os projetos da sua organização.

Este endpoint é idêntico ao existente, mas com a adição do 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
}

Este artigo foi útil?