OpenAI
Тази страница е машинно преведена. Вижте оригиналната статия на английски език.

EKM (External Keys) в Management API

Управлявайте външни ключове за EKM чрез Management API

Актуализирано: 3 days ago

Обобщение

Достъп

  • EKM endpoints са достъпни в Management API чрез Admin API Key. https://platform.openai.com/settings/organization/admin-keys (не използвайте обикновен API ключ). Admin API ключовете са достъпни за собствениците на организацията.

  • Използвайте api.external_keys.write, за да създавате или изтривате външни ключове, и api.external_keys.read, за да изброявате или валидирате външни ключове. Един ключ се нуждае и от двата обхвата само ако трябва да извършва както операции за четене, така и за запис.

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

Ограничения

  • Първо трябва да тествате EKM в нов проект чрез Management API.

  • Препоръчваме да създавате нови проекти за вашите EKM работни натоварвания. Ако обаче искате EKM в съществуващ проект, можем да ви добавим към feature flag. Моля, имайте предвид следните добри практики, преди да внедрите EKM в съществуващите си производствени проекти.

    • Първо тествайте всички API функции, които използвате в production, във вашия тестов EKM API проект

    • Прилагайте постепенно внедряване, вместо да активирате EKM във всички production API проекти наведнъж

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

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

AWS

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

  • type: string - винаги „aws“

  • name: string - удобно име за вашата конфигурация

  • role_arn: string - Role ARN, която OpenAI ще приеме във вашия облак

  • kms_arn: string - ARN в Key Management System за главния ключ, който управлявате

  • 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 - пулът, съдържащ доставчика на 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 - key ring в Key Management System, съдържащ главния ключ, който управлявате

  • kms_key_name: string - името на главния ключ в Key Management System

  • kms_key_location: string - регионът, в който се намира главният ключ в Key Management System

Ако вашият 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, за да проверите няколко неща

  • Външната ви облачна конфигурация остава валидна за 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 на външен ключ

Това е същият съществуващ endpoint Create Project, но с добавен параметър 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 на външен ключ

Това е същият съществуващ endpoint Update Project, но с добавен параметър external_key_id в заявката и отговора.


Препоръчваме да създавате нови API проекти за вашите EKM работни натоварвания. Ако искате EKM във всички съществуващи API проекти, обърнете се към вашия account director и ще ви добавим към feature flag. Моля, имайте предвид следните добри практики, преди да внедрите EKM в съществуващите си производствени проекти.

  • Първо тествайте всички API функции, които използвате в production, във вашия тестов EKM API проект

  • Прилагайте постепенно внедряване, вместо да активирате EKM във всички production 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
}

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