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

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

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

Оновлено: 2 hours ago

Підсумок

Доступ

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

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

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

  • Конфігурація 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 у наявних проєктах у виробничому середовищі, ознайомтеся з наведеними нижче рекомендаціями.

    • Спочатку перевірте всі функції 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, яким ви керуєте.

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

OCI

Налаштуйте й увімкніть ключ AES-256 та надайте OpenAI доступ до нього. Ключ повинен мати тег вільної форми openai_organization_id, значенням якого є ваш ID організації OpenAI. Інструкції з налаштування див. у статті Налаштування OCI Vault для корпоративного керування ключами.

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

  • type: string — завжди "oci"

  • purpose: string — "ekm"; значення за замовчуванням, якщо параметр не вказано

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

  • region: string — регіон OCI, де розміщено ваше сховище та ключ

  • vault_ocid: string — повний OCID вашого сховища

  • key_ocid: string — повний OCID вашого ключа AES-256

Не передавайте key_version_ocid для EKM.

curl -X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys" \
-d '{
"type": "oci",
"purpose": "ekm",
"name": "OCI EKM Config",
"region": "us-ashburn-1",
"vault_ocid": "<VAULT_OCID>",
"key_ocid": "<AES_KEY_OCID>"
}'

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

{
"id": "extkey_xxxx",
"object": "organization.external_key",
"created_at": 1746175499,
"api_project_ids": [],
"type": "oci",
"purpose": "ekm",
"name": "OCI EKM Config",
"region": "us-ashburn-1",
"vault_ocid": "<VAULT_OCID>",
"key_ocid": "<AES_KEY_OCID>"
}

У разі успіху API повертає HTTP 200. Збережіть отриманий id і використовуйте його як external_key_id під час створення проєкту. Наявні операції отримання списку, отримання окремої реєстрації, перевірки та видалення також застосовуються до реєстрацій OCI.

Для відновлення PSP використовуйте окрему реєстрацію RSA-3072 із purpose: "psp_decryption" і точним значенням key_version_ocid. Установіть для psp_decryption_key_id значення ID цієї реєстрації в OpenAI. Для цього ключа RSA компанії OpenAI потрібен лише доступ на читання метаданих і відкритих ключів. Повні інструкції з налаштування див. у статті Налаштування асиметричних ключів — OCI Vault.

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

Примітка: видалення заблоковано, доки активний проєкт або робочий простір використовує цю реєстрацію. Для EKM спочатку архівуйте пов’язані API-проєкти; реєстрація EKM, пов’язана з робочим простором, залишається захищеною від видалення. Для відновлення PSP перед видаленням реєстрації замініть або очистьте psp_decryption_key_id в кожному активному проєкті, що посилається на неї. Видалення реєстрації в OpenAI не видаляє хмарний ключ.

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

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

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

Без фільтра за призначенням список містить реєстрації як для EKM, так і для відновлення PSP. Використовуйте ?purpose=ekm або ?purpose=psp_decryption для фільтрування за призначенням.

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

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 досі має доступ до вашого хмарного ключа.

  • Для EKM OpenAI перевіряє можливість шифрування та розшифрування за допомогою ключа. Відомості про відкликання та кешування див. у рекомендаціях щодо життєвого циклу ключів.

  • Для відновлення PSP OpenAI отримує відкритий ключ зареєстрованої версії та порівнює його зі збереженим знімком. Успішна перевірка не підтверджує, що ваш обліковий запис для відновлення має змогу виконувати розшифрування. Невдала перевірка не видаляє й не замінює збережений знімок відкритого ключа.

Отримання реєстрації за допомогою GET повертає збережену конфігурацію й не перевіряє повторно доступ до вашого хмарного ключа.

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

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, які використовуєте у виробничому середовищі, у своєму тестовому 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
}

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