OpenAI
Esta página foi traduzida automaticamente. Ver o artigo original em inglês.

EKM (Chaves Externas) na API de Gestão

Gerir chaves externas para EKM através da API de Gestão

Atualizado: 6 days ago

Resumo

Acesso

  • Os endpoints de EKM estão acessíveis na API de Gestão através de uma Admin API Key. https://platform.openai.com/settings/organization/admin-keys (não utilize uma API key normal). As Admin API keys estão disponíveis para os proprietários da organização.

  • Utilize api.external_keys.write para criar ou eliminar chaves externas, e api.external_keys.read para listar ou validar chaves externas. Uma única chave só precisa de ambos os scopes se tiver de executar operações de leitura e de escrita.

  • Atualmente, precisamos de ativar uma feature flag para a sua organização nestes endpoints. Sabe que tem a feature flag se vir **external_key_id **devolvido pelo endpoint existente List Projects: https://api.openai.com/v1/organization/projects

Utilização

Restrições

  • Tem primeiro de testar o EKM num novo projeto através da API de Gestão.

  • Recomendamos criar novos projetos para as suas cargas de trabalho de EKM. No entanto, se quiser EKM num projeto existente, podemos adicioná-lo à feature flag. Tenha em conta as seguintes boas práticas antes de implementar o EKM nos seus projetos de produção existentes.

    • Teste primeiro, no seu projeto de teste da API EKM, todas as funcionalidades da API que utiliza em produção

    • Aplique uma implementação gradual em vez de preencher com EKM todos os projetos da API de produção de uma só vez

Endpoints ao nível da organização

Registar uma chave externa na sua organização

AWS

Pedido de exemplo

  • type: string - sempre “aws”

  • name: string - Um nome amigável para a sua configuração

  • role_arn: string - O ARN da função que a OpenAI irá assumir na sua cloud

  • kms_arn: string - O ARN do Key Management System da chave mestra que gere

  • external_id: string - O ID da sua organização ou o ID do projeto 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": "Configuração EKM AWS",
  "role_arn": "arn:aws:iam::<12_DIGIT_ACCOUNT_NUMBER>:role/<ROLE>",
  "kms_arn": "arn:aws:kms:<REGION>:<ACCOUNT_NUMBER>:key/<UUID>",
  "external_id": <o id da sua organização ou do projeto>
}'

Resposta de exemplo

{
  "id": "extkey_xxxx",
  "object": "organization.external_key",
  "created_at": 1746175499,
  "api_project_ids": [],
  "type": "aws",
  "name": "Configuração EKM AWS",
  "role_arn": "arn:aws:iam::<ACCOUNT_NUMBER>:role/<ROLE>",
  "kms_arn": "arn:aws:kms:<REGION>:<ACCOUNT_NUMBER>:key/<UUID>",
  "external_id": <o id da sua organização ou do projeto>
}  

GCP

Pedido de exemplo

  • type: string - sempre "gcp",

  • name: string - Um nome amigável para a sua configuração

  • workload_identity_project_number: string - O número de projeto GCP de 12 dígitos onde registou a workload identity da OpenAI

  • workload_identity_pool_id: string - O pool que contém o fornecedor de Workload Identity que registou para a OpenAI

  • workload_identity_provider_id: string - O fornecedor de Workload Identity que registou para a OpenAI

  • audience: string - A audience que a OpenAI deve passar no token quando assumimos uma função através do seu GCP STS

  • kms_project_id: string - O nome do projeto GCP onde o seu KMS está alojado

  • kms_key_ring_name: string - O key ring do Key Management System que contém a chave mestra que gere

  • kms_key_name: string - O nome da chave mestra do Key Management System

  • kms_key_location: string - A região onde a sua chave mestra do Key Management System está localizada

Se o seu KMS estiver alojado num projeto GCP diferente daquele onde registou a Workload Identity da OpenAI, certifique-se de que o projeto que contém a Workload Identity da OpenAI tem pelo menos o KMS ativado, acedendo a 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": "Configuração EKM GCP",
   "workload_identity_project_number": "123456789012",
   "workload_identity_pool_id": "openai-azure",
   "workload_identity_provider_id": "openai-ekm-service-role",
   "audience": <o id da sua organização ou do projeto>,
   "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"
}'

Resposta de exemplo

{
  "id": "extkey_xxxxxx",
  "object": "organization.external_key",
  "created_at": 1746174349,
  "api_project_ids": [],
  "type": "gcp",
  "name": "Configuração EKM GCP",
  "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": <o id da sua organização ou do projeto>,
  "kms_project_id": "adjective-noun-12345",
  "workload_identity_pool_id": "openai-azure",
  "workload_identity_provider_id": "openai-ekm-service-role"
}

Azure

Pedido de exemplo

  • type: string - sempre "azure",

  • name: string - Um nome amigável para a sua configuração

  • tenant_id: string - O UUID do seu tenant Azure

  • vault_uri: string - O URI do cofre Azure que contém a chave mestra que gere

  • key_name: string - O nome da chave mestra do Azure Key Vault que gere.

curl -X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys" \
-d '{
  "type": "azure",
  "name": "Configuração EKM Azure",
  "tenant_id": "<UUID>",
  "vault_uri": "https://<VAULT_NAME>.vault.azure.net/",
  "key_name": "org-xxx--some-key"
}'

Resposta de exemplo

{
  "id": "extkey_xxxx",
  "object": "organization.external_key",
  "created_at": 1746174377,
  "api_project_ids": [],
  "type": "azure",
  "name": "Configuração EKM Azure",
  "tenant_id": "<UUID>",
  "vault_uri": "https://<VAULT_NAME>.vault.azure.net/",
  "key_name": "org-xxx--some-key"
}

Eliminar uma chave externa registada na sua organização

Nota: Só pode eliminar uma chave externa se esta não estiver associada a quaisquer projetos ativos. Se estiver associada a um projeto ativo, tem primeiro de arquivar esse projeto.

Pedido de exemplo

curl -X DELETE \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys/extkey_xxxx"

Resposta de exemplo

{
  "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": "Configuração EKM AWS",
  "role_arn": "arn:aws:iam::<ACCOUNT_NUMBER>:role/<ROLE>"
}

Obter as chaves externas registadas na sua organização

Pedido de exemplo

curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys"

Resposta de exemplo

{
  "object": "list",
  "data": [
    {
      "id": "extkey_xxxx",
      "object": "organization.external_key",
      "created_at": 1746127808,
      "api_project_ids": [],
      "type": "aws",
      "name": "Configuração EKM AWS",
      "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

Pode utilizar este endpoint para verificar várias coisas

  • A sua configuração de cloud externa continua válida com a OpenAI depois de ter efetuado alterações (verá uma resposta de sucesso)

  • A revogação da sua chave foi feita corretamente, está a ser processada pela OpenAI e produzirá efeito após o fim do TTL de cache de 1 hora (verá uma resposta de erro)

Pedido de exemplo

curl -X POST -H "Authorization: Bearer $TOKEN"
"https://api.openai.com/v1/organization/external_keys/extkey_xxx/validate"

Resposta de exemplo

{
 "status": "success"
}

Ou um erro apresentado pelo fornecedor de cloud.

Endpoints ao nível do projeto

Criar um novo projeto com um ID de chave externa

É igual ao endpoint existente Create Project, com a adição do parâmetro external_key_id no pedido e na resposta.

Pedido de exemplo

curl -X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/projects" \
-d '{
   "name": "Algum Projeto",
   "external_key_id": "extkey_xxxx"
}'

Resposta de exemplo

{
  "object": "project",
  "id": "proj_xxxxx",
  "title": "Algum Projeto",
  "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

É igual ao endpoint existente Update Project, com a adição do parâmetro external_key_id no pedido e na resposta.

Recomendamos criar novos projetos de API para as suas cargas de trabalho de EKM. Se quiser EKM em todos os seus projetos de API existentes, peça-o ao seu diretor de conta e adicioná-lo-emos à feature flag. Tenha em conta as seguintes boas práticas antes de implementar o EKM nos seus projetos de produção existentes.

  • Teste primeiro, no seu projeto de teste da API EKM, todas as funcionalidades da API que utiliza em produção

  • Aplique uma implementação gradual em vez de preencher com EKM todos os projetos da API de produção de uma só vez

Pedido de exemplo

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"
}'

Listar todos os projetos da sua organização

É igual ao endpoint existente, mas com a adição de external_key_id na resposta da API

Pedido de exemplo

curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/projects"

Resposta de exemplo

{
  "object": "list",
  "data": [
    {
      "object": "organization.project",
      "id": "proj_xxxx",
      "name": "Nome do Projeto",
      "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?