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

Підсумок

Доступ

Кінцеві точки EKM доступні в API керування за допомогою ключа API адміністратора. https://platform.openai.com/settings/organization/admin-keys (не використовуйте звичайний ключ API). Ключі API адміністратора доступні власникам організації.
Використовуйте api.external_keys.write для створення або видалення зовнішніх ключів, а api.external_keys.read — для отримання їхнього списку або перевірки. Одному ключу потрібні обидва дозволи, лише якщо він має виконувати операції і читання, і запису.
Наразі для доступу до цих кінцевих точок ми маємо ввімкнути прапорець функції для вашої організації. Прапорець функції ввімкнено, якщо наявна кінцева точка отримання списку проєктів повертає external_key_id: https://api.openai.com/v1/organization/projects.

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

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

Обмеження

Спершу потрібно протестувати EKM у новому проєкті через API керування.
Рекомендуємо створювати нові проєкти для робочих навантажень з EKM. Однак якщо ви хочете використовувати EKM у наявному проєкті, ми можемо ввімкнути для вас прапорець функції. Перш ніж упроваджувати EKM у наявних проєктах у виробничому середовищі, ознайомтеся з наведеними нижче рекомендаціями.
- Спершу перевірте всі функції API, які використовуєте у виробничому середовищі, у тестовому API-проєкті з EKM.
- Упроваджуйте EKM поступово, а не в усіх API-проєктах виробничого середовища одночасно.

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

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

AWS

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

type: рядок — завжди «aws»
name: рядок — зрозуміла назва конфігурації
role_arn: рядок — ARN ролі, яку OpenAI прийматиме у вашій хмарі
kms_arn: рядок — ARN у системі керування ключами для головного ключа, яким ви керуєте
external_id: рядок — ID вашої організації або 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: рядок — завжди «gcp»,
name: рядок — зрозуміла назва конфігурації
workload_identity_project_number: рядок — числовий номер проєкту GCP, у якому ви зареєстрували ідентичність робочого навантаження OpenAI
workload_identity_pool_id: рядок — пул, що містить постачальника Workload Identity, зареєстрованого вами для OpenAI
workload_identity_provider_id: рядок — постачальник Workload Identity, якого ви зареєстрували для OpenAI
audience: рядок — аудиторія, яку OpenAI має передавати в токені під час прийняття ролі через вашу службу GCP STS
kms_project_id: рядок — назва проєкту GCP, у якому розміщено вашу KMS
kms_key_ring_name: рядок — в’язка ключів у системі керування ключами, що містить головний ключ, яким ви керуєте
kms_key_name: рядок — назва головного ключа в системі керування ключами
kms_key_location: рядок — регіон, у якому розміщено головний ключ вашої системи керування ключами

Якщо ваша 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: рядок — завжди «azure»,
name: рядок — зрозуміла назва конфігурації
tenant_id: рядок — UUID вашого клієнта Azure
vault_uri: рядок — URI сховища Azure, що містить головний ключ, яким ви керуєте
key_name: рядок — назва головного ключа Azure Key Vault, яким ви керуєте.
- Назва має бути у форматі <org-xxx>--<any_name>
- де org-xxx — ID вашої організації OpenAI, який можна знайти за посиланням https://platform.openai.com/settings/organization/general

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

Перевірка зовнішнього ключа

За допомогою цієї кінцевої точки можна перевірити:

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

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

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

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

{
  "status": "success"
}

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

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

Створення нового проєкту з ID зовнішнього ключа

Це та сама кінцева точка створення проєкту, що й раніше, але до запиту й відповіді додано параметр 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": "organization.project",
  "id": "proj_xxxxx",
  "name": "Some Project",
  "external_key_id": "extkey_xxxx",
  "created_at": 1740012721,
  "archived_at": null,
  "status": "active"
}

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

Це та сама кінцева точка оновлення проєкту, що й раніше, але до запиту й відповіді додано параметр external_key_id.

Рекомендуємо створювати нові API-проєкти для робочих навантажень з EKM. Якщо ви хочете використовувати EKM у всіх наявних API-проєктах, зверніться до менеджера вашого облікового запису, і ми ввімкнемо для вас прапорець функції. Перш ніж упроваджувати 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"
}'

Отримання списку всіх проєктів вашої організації

Це та сама кінцева точка, що й раніше, але у відповідь API додано external_key_id.

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

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
}

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

Підсумок

Доступ

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

Обмеження

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

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

AWS

GCP

Azure

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

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

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

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

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

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

Перевірка зовнішнього ключа

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

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

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

Створення нового проєкту з ID зовнішнього ключа

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

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

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

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

Отримання списку всіх проєктів вашої організації

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

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

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