Дознајте како да управувате со надворешни клучеви за 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 на организација или 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"
}'

Прикажете ги сите проекти во вашата организација

Ова е исто како постојната крајна точка, но со додадено 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 (надворешни клучеви) во API за управување

Резиме

Пристап

Користење

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

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

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

AWS

GCP

Azure

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

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

Пример за одговор

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

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

Пример за одговор

Проверете ја валидноста на надворешен клуч

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

Пример за одговор

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

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

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

Пример за одговор

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

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

Прикажете ги сите проекти во вашата организација

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

Пример за одговор

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