Научете как да управлявате външни ключове за 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: 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 – числовият номер на 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, уверете се, че поне KMS е активирана в проекта, съдържащ Workload Identity на OpenAI, като посетите 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, който управлявате.
- То трябва да е във формат <org-xxx>--<any_name>
- където org-xxx е идентификаторът на организацията ви в 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 на ниво проект

Създаване на нов проект с идентификатор на външен ключ

Това е същата крайна точка като съществуващата за създаване на проект, но с добавен параметър 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"
}

[Ограничен достъп] Актуализиране на съществуващ проект с идентификатор на външен ключ

Това е същата крайна точка като съществуващата за актуализиране на проект, но с добавен параметър 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"
}'

Извеждане на списък с всички проекти във вашата организация

Това е същата крайна точка като съществуващата, но с добавено поле 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
}

EKM (External Keys) в Management API

Обобщение

Достъп

Използване

Ограничения

endpoints на ниво организация

Регистриране на външен ключ във вашата организация

AWS

GCP

Azure

Изтриване на външен ключ, регистриран във вашата организация

Примерна заявка

Примерен отговор

Получаване на външните ключове, регистрирани във вашата организация

Примерна заявка

Примерен отговор

Проверка на валидността на външен ключ

Примерна заявка

Примерен отговор

endpoints на ниво проект

Създаване на нов проект с идентификатор на външен ключ

Примерна заявка

Примерен отговор

[Ограничен достъп] Актуализиране на съществуващ проект с идентификатор на външен ключ

Примерна заявка

Извеждане на списък с всички проекти във вашата организация

Примерна заявка

Примерен отговор

Беше ли Ви полезна тази статия?