OpenAI
Для перекладу цієї сторінки виконано машинний переклад. Ви можете переглянути оригінальну статтю англійською.

EKM (зовнішні ключі) у Management API

Керуйте зовнішніми ключами для EKM за допомогою Management API

Оновлено: yesterday

Підсумок

Доступ

  • Endpoints EKM доступні в Management API за допомогою ключа Admin API. https://platform.openai.com/settings/organization/admin-keys (не використовуйте звичайний ключ API). Ключі Admin API доступні власникам організації.

  • Використовуйте api.external_keys.write, щоб створювати або видаляти зовнішні ключі, і api.external_keys.read, щоб переглядати список або перевіряти зовнішні ключі. Одному ключу потрібні обидві області доступу лише тоді, коли він має виконувати і операції читання, і операції запису.

  • Наразі нам потрібно ввімкнути feature flag для вашої організації на цих endpoints. Ви знатимете, що feature flag увімкнено, якщо побачите, що external_key_id повертається з наявного endpoint List Projects: https://api.openai.com/v1/organization/projects

Використання

  • Ваша конфігурація EKM реєструється на рівні організації через новий endpoint https://api.openai.com/v1/organization/external_keys

  • Після реєстрації конфігурації EKM повертається external_key_id у форматі extkey_xxxx

  • Конфігурації EKM активуються на рівні проєкту шляхом передавання external_key_id у тілі запиту до наявного endpoint Create Project https://api.openai.com/v1/organization/projects

Обмеження

  • Спочатку потрібно протестувати EKM у новому проєкті через Management API.

  • Ми рекомендуємо створювати нові проєкти для ваших робочих навантажень EKM. Однак якщо ви хочете використовувати EKM у наявному проєкті, ми можемо додати вас до feature flag. Перш ніж розгортати EKM у наявних виробничих проєктах, зверніть увагу на наведені нижче найкращі практики.

    • Спершу протестуйте всі функції API, які використовуєте у виробництві, у тестовому API-проєкті EKM

    • Застосовуйте поступове розгортання, а не вмикайте EKM одразу в усіх виробничих API-проєктах

Endpoints рівня організації

Зареєструйте зовнішній ключ у вашій організації

AWS

Приклад запиту

  • type: string — завжди «aws»

  • name: string — зрозуміла назва вашої конфігурації

  • role_arn: string — ARN ролі, яку OpenAI прийматиме у вашій хмарі

  • kms_arn: string — ARN системи керування ключами для майстер-ключа, яким ви керуєте

  • external_id: string — ідентифікатор вашої організації або 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>
}'

Приклад відповіді

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

Приклад запиту

  • type: string — завжди «gcp»,

  • name: string — зрозуміла назва вашої конфігурації

  • workload_identity_project_number: string — 12-значний номер проєкту GCP, у якому ви зареєстрували ідентичність робочого навантаження OpenAI

  • workload_identity_pool_id: string — пул, що містить провайдера Workload Identity, якого ви зареєстрували для OpenAI

  • workload_identity_provider_id: string — провайдер Workload Identity, якого ви зареєстрували для OpenAI

  • audience: string — аудиторія, яку OpenAI має передавати в токені, коли ми приймаємо роль через ваш GCP STS

  • kms_project_id: string — назва проєкту GCP, у якому розміщено ваш KMS

  • kms_key_ring_name: string — зв’язка ключів системи керування ключами, що містить майстер-ключ, яким ви керуєте

  • kms_key_name: string — назва майстер-ключа системи керування ключами

  • kms_key_location: string — регіон, де розташовано ваш майстер-ключ системи керування ключами

Якщо ваш KMS розміщено в іншому проєкті GCP, ніж той, у якому ви зареєстрували Workload Identity OpenAI, переконайтеся, що в проєкті з Workload Identity OpenAI принаймні ввімкнено KMS, перейшовши на 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"
}'

Приклад відповіді

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

Приклад запиту

  • type: string — завжди «azure»,

  • name: string — зрозуміла назва вашої конфігурації

  • tenant_id: string — UUID вашого клієнта Azure

  • vault_uri: string — URI сховища Azure, що містить майстер-ключ, яким ви керуєте

  • key_name: string — назва майстер-ключа Azure Key Vault, яким ви керуєте.

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

Приклад відповіді

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

Видаліть зовнішній ключ, зареєстрований у вашій організації

Примітка. Зовнішній ключ можна видалити лише тоді, коли він не пов’язаний з активними API-проєктами або робочим простором. Якщо він пов’язаний з активним API-проєктом, спершу архівуйте цей проєкт. Якщо він пов’язаний із робочим простором, ключ видалити не можна.

Приклад запиту

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

Приклад відповіді

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

Отримайте зовнішні ключі, зареєстровані у вашій організації

Приклад запиту

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

Приклад відповіді

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

Перевірте зовнішній ключ

Цей endpoint можна використовувати, щоб перевірити кілька речей

  • Ваша зовнішня хмарна конфігурація залишається дійсною для OpenAI після внесених змін (ви побачите відповідь про успіх)

  • Відкликання ключа виконано правильно, обробляється OpenAI і набуде чинності після завершення 1-годинного TTL кешу (ви побачите відповідь із помилкою)

Приклад запиту

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

Приклад відповіді

{
 "status": "success"
}

Або помилка, передана від хмарного провайдера.

Endpoints рівня проєкту

Створіть новий проєкт з ідентифікатором зовнішнього ключа

Це те саме, що й наявний endpoint Create Project, але з додаванням параметра external_key_id у запиті та відповіді.

Приклад запиту

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

Приклад відповіді

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

[Обмежено] Оновіть наявний проєкт за допомогою ідентифікатора зовнішнього ключа

Це те саме, що й наявний endpoint Update Project, але з додаванням параметра external_key_id у запиті та відповіді.


Ми рекомендуємо створювати нові API-проєкти для ваших робочих навантажень EKM. Якщо ви хочете використовувати EKM у всіх наявних API-проєктах, зверніться до свого менеджера облікового запису, і ми додамо вас до feature flag. Перш ніж розгортати EKM у наявних виробничих проєктах, зверніть увагу на наведені нижче найкращі практики.

  • Спершу протестуйте всі функції API, які використовуєте у виробництві, у тестовому API-проєкті EKM

  • Застосовуйте поступове розгортання, а не вмикайте EKM одразу в усіх виробничих API-проєктах

Приклад запиту

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

Перегляньте всі проєкти у вашій організації

Це те саме, що й наявний endpoint, але з додаванням external_key_id у відповідь API

Приклад запиту

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

Приклад відповіді

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

Чи була ця стаття корисною?