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

EKM (Chaves externas) na API de Gestão

Saiba como gerir chaves externas para EKM através da API de gestão.

Atualizado: 14 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 administrador. https://platform.openai.com/settings/organization/admin-keys (não utilize uma chave de API normal). As chaves de API de administrador 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 chave só precisa de ambos os âmbitos se tiver de realizar operações de leitura e de escrita.

  • Atualmente, temos de ativar um sinalizador de funcionalidade para dar à sua organização acesso a estes endpoints. O sinalizador de funcionalidade está ativado se external_key_id for devolvido pelo endpoint existente de listagem de projetos: https://api.openai.com/v1/organization/projects.

Utilização

Restrições

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

  • Recomendamos a criação de novos projetos para as suas cargas de trabalho de EKM. No entanto, se pretender utilizar EKM num projeto existente, podemos ativar o sinalizador de funcionalidade para si. Tenha em conta as seguintes boas práticas antes de implementar EKM nos seus projetos de produção existentes.

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

    • Faça uma implementação gradual, em vez de ativar EKM em todos os projetos de API em produção de uma só vez.

Endpoints ao nível da organização

Registar uma chave externa na sua organização

AWS

Exemplo de pedido:

  • type: string - sempre «aws»

  • name: string - Um nome descritivo 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 sistema de gestão de chaves correspondente à chave mestra que gere

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

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 pedido:

  • type: string - sempre «gcp»,

  • name: string - Um nome descritivo para a sua configuração

  • workload_identity_project_number: string - O número do projeto GCP onde registou a identidade da carga de trabalho da OpenAI

  • workload_identity_pool_id: string - O conjunto 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 - O público-alvo 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 se encontra o seu KMS

  • kms_key_ring_name: string - O conjunto 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 chave mestra do seu 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"
}'

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 pedido:

  • type: string - sempre «azure»,

  • name: string - Um nome descritivo para a sua configuração

  • tenant_id: string - O UUID do seu inquilino Azure

  • vault_uri: string - O URI do cofre do 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"
}'

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

Eliminar uma chave externa registada na sua organização

Nota: Só pode eliminar uma chave externa se esta não estiver associada a nenhum projeto de API ativo nem a nenhum 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.

Exemplo de pedido

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

Obter as chaves externas registadas na sua organização

Exemplo de pedido

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

Pode utilizar este endpoint para verificar vários aspetos:

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

  • A revogação da sua chave foi efetuada corretamente, está a ser processada pela OpenAI e terá efeito quando os TTL de 1 hora da cache expirarem (receberá uma resposta de erro).

Exemplo de pedido

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

Exemplo de resposta

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

Este endpoint é igual ao endpoint existente de criação de projetos, mas inclui o parâmetro external_key_id no pedido e na resposta.

Exemplo de pedido

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

[Restrito] Atualizar um projeto existente com um ID de chave externa

Este endpoint é igual ao endpoint existente de atualização de projetos, mas inclui o 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 de EKM. Se pretender utilizar EKM em todos os seus projetos de API existentes, contacte o seu gestor de conta e ativaremos o sinalizador de funcionalidade para si. Tenha em conta as seguintes boas práticas antes de implementar EKM nos seus projetos de produção existentes.

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

  • Faça uma implementação gradual, em vez de ativar EKM em todos os projetos de API em produção de uma só vez.

Exemplo de pedido

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

Este endpoint é igual ao existente, mas inclui external_key_id na resposta da API.

Exemplo de pedido

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?