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

EKM (външни ключове) в Management API

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

Актуализирано: 4 hours ago

Обобщение

Достъп

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

Ограничения

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

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

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

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

Крайни точки на ниво организация

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

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 - Audience, който OpenAI трябва да предаде в токена, когато приемаме роля чрез вашия GCP STS

  • kms_project_id: string - Името на GCP проекта, в който се намира вашият KMS

  • kms_key_ring_name: string - Key Management System key ring, съдържащ главния ключ, който управлявате

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

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

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

Забележка: Можете да изтриете външен ключ само ако не е свързан с активни проекти. Ако е свързан с активен проект, първо трябва да архивирате този проект.

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

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 и ще влезе в сила след изтичане на 1-часовите TTL на кеша (ще видите отговор с грешка)

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

curl -X POST -H "Authorization: Bearer $TOKEN"
"https://api.openai.com/v1/organization/external_keys/extkey_xxx/validate"

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

{
 "status": "success"
}

Или грешка, възникнала от облачния доставчик.

Крайни точки на ниво проект

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

Това е същото като съществуващата крайна точка 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": "Някакъв проект",
   "external_key_id": "extkey_xxxx"
}'

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

{
  "object": "project",
  "id": "proj_xxxxx",
  "title": "Някакъв проект",
  "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, с добавяне на параметъра external_key_id в заявката и отговора.

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

  • Първо тествайте всички 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"
}'

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

Това е същото като съществуващата крайна точка, но с добавяне на 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": "Име на проект",
      "external_key_id": "extkey_xxxx",
      "created_at": 1717798982,
      "archived_at": null,
      "status": "active"
    }
  ],
  "first_id": "proj_xxxx",
  "last_id": "proj_xxxx",
  "has_more": true
}

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