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 usando a API de Gestão

Atualizado: 21 days ago

Resumo

Acesso

  • Os endpoints de EKM estão acessíveis na API de Gestão através de uma Chave de API de Admin. https://platform.openai.com/settings/organization/admin-keys (não utilize uma chave de API normal). As chaves de API de Admin estão disponíveis para 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 âmbitos se tiver de realizar operações de leitura e escrita.

  • Atualmente, temos de ativar estes endpoints para a sua organização através de uma feature flag. Saberá que tem a feature flag se vir external_key_id devolvido pelo endpoint List Projects existente: https://api.openai.com/v1/organization/projects

Utilização

Restrições

  • Primeiro, tem de testar EKM num novo projeto através da API de Gestão.

  • Recomendamos a criação de novos projetos para as suas cargas de trabalho EKM. Contudo, se pretender usar EKM num projeto existente, podemos adicioná-lo à feature flag. Tenha em conta as seguintes melhores práticas antes de implementar EKM nos seus projetos de produção existentes.

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

    • Faça uma implementação gradual em vez de ativar EKM em todos os projetos de 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 legível para a sua configuração

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

  • kms_arn: string - O ARN do Sistema de Gestão de Chaves para a chave mestra que gere

  • external_id: string - O ID da sua organização ou do 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>
}'

Resposta de exemplo

{
  "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

Pedido de exemplo

  • type: string - sempre  "gcp",

  • name: string - Um nome legível para a sua configuração

  • workload_identity_project_number: string - O número de 12 dígitos do projeto GCP 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 audiência que a OpenAI deve passar no token quando assumimos uma função através do seu STS da GCP

  • kms_project_id: string - O nome do projeto GCP onde reside o seu KMS

  • kms_key_ring_name: string - O anel de chaves do Sistema de Gestão de Chaves que contém a chave mestra que gere

  • kms_key_name: string - O nome da chave mestra do Sistema de Gestão de Chaves

  • kms_key_location: string - A região onde se encontra a sua chave mestra do Sistema de Gestão de Chaves

Se o seu KMS estiver 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": "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"
}'

Resposta de exemplo

{
  "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

Pedido de exemplo

  • type: string - sempre  "azure",

  • name: string - Um nome legível para a sua configuração

  • tenant_id: string - O UUID do seu inquilino 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": "Azure EKM Config",
  "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": "Azure EKM Config",
  "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 projetos de API ativos nem a um espaço de trabalho. Se estiver associada a um projeto de API ativo, arquive primeiro esse projeto. Se estiver associada a um espaço de trabalho, a chave não pode ser eliminada.

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": "AWS EKM Config",
  "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": "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

Pode utilizar este endpoint para verificar vários aspetos

  • Que a sua configuração de cloud externa continua válida com a OpenAI depois de ter feito alterações (verá uma resposta de êxito)

  • Que a revogação da sua chave foi feita corretamente, está a ser processada pela OpenAI e entrará em vigor depois de expirarem os TTLs da 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 foi apresentado um erro do fornecedor de cloud.

Endpoints ao nível do projeto

Criar um novo projeto com um ID de chave externa

É igual ao endpoint Create Project existente, 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": "Some Project",
   "external_key_id": "extkey_xxxx"
}'

Resposta de exemplo

{
  "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

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


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

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

  • Faça uma implementação gradual em vez de ativar EKM em todos os projetos de 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 na 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": "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?