OpenAI
Оваа страница беше машински преведена. Погледнете ја оригиналната статија на англиски јазик.

EKM (надворешни клучеви) во API за управување

Управувајте со надворешни клучеви за EKM преку API за управување

Ажурирано: last month

Резиме

Пристап

  • EKM endpoints се достапни во API за управување преку администраторски API-клуч. https://platform.openai.com/settings/organization/admin-keys (не користете обичен API-клуч). Администраторските API-клучеви им се достапни на сопствениците на организацијата.

  • Користете api.external_keys.write за создавање или бришење надворешни клучеви, а api.external_keys.read за наведување или проверка на надворешни клучеви. Еден клуч има потреба од двата опсега само ако мора да извршува и операции за читање и операции за запишување.

  • Во моментов треба да вклучиме feature flag за вашата организација за овие endpoints. Ќе знаете дека го имате feature flag ако видите external_key_id вратен од постојниот List Projects endpoint: 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 во телото на постојниот Create Project endpoint https://api.openai.com/v1/organization/projects

Ограничувања

  • Прво мора да го тестирате EKM на нов проект преку API за управување.

  • Препорачуваме да подигнете нови проекти за вашите EKM-работни оптоварувања. Меѓутоа, ако сакате EKM на постоен проект, можеме да ве додадеме во feature flag. Имајте ги предвид следниве најдобри практики пред да го воведете EKM во вашите постојни продукциски проекти.

    • Прво тестирајте ги сите API-функции што ги користите во продукција во вашиот тестен EKM API-проект

    • Применете постепено воведување наместо да го додавате EKM на сите продукциски API-проекти одеднаш

Endpoints на ниво на организација

Регистрирајте надворешен клуч во вашата организација

AWS

Пример барање

  • type: string -  секогаш „aws“

  • name: string -  Пријателско име за вашата конфигурација

  • role_arn: string - ARN на улогата што OpenAI ќе ја преземе во вашиот облак

  • kms_arn: string - ARN на системот за управување со клучеви за главниот клуч со кој управувате

  • external_id: string - 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: string - секогаш  „gcp“,

  • name: string - Пријателско име за вашата конфигурација

  • workload_identity_project_number: string - 12-цифрениот број на GCP-проектот каде што го регистриравте Workload Identity на OpenAI

  • workload_identity_pool_id: string - Pool што го содржи давателот на Workload Identity што го регистриравте за OpenAI

  • workload_identity_provider_id: string - Давателот на Workload Identity што го регистриравте за OpenAI

  • audience: string - Вредноста audience што 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 tenant

  • 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 можете да го користите за проверка на неколку работи

  • Вашата надворешна cloud-конфигурација останува валидна со 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 на ниво на проект

Создајте нов проект со ID на надворешен клуч

Ова е исто како постојниот Create Project endpoint, со додаден параметар 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,
}

[Ограничено] Ажурирајте постоен проект со ID на надворешен клуч

Ова е исто како постојниот Update Project endpoint, со додаден параметар external_key_id во барањето и одговорот.


Препорачуваме да подигнете нови API-проекти за вашите EKM-работни оптоварувања. Ако сакате EKM на сите ваши постојни API-проекти, побарајте од директорот на вашата сметка и ќе ве додадеме во feature flag. Имајте ги предвид следниве најдобри практики пред да го воведете EKM во вашите постојни продукциски проекти.

  • Прво тестирајте ги сите API-функции што ги користите во продукција во вашиот тестен EKM API-проект

  • Применете постепено воведување наместо да го додавате 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
}

Дали оваа статија ви беше корисна?