الملخص
إمكانية الوصول
يمكن الوصول إلى نقطة النهاية الخاصة بنظام EKM في واجهة برمجة تطبيقات الإدارة عبر مفتاح API للمسؤول. https://platform.openai.com/settings/organization/admin-keys (لا تستخدم مفتاح API عاديًا). مفاتيح API للمسؤول متاحة لمالكي المؤسسات.
استخدم
api.external_keys.writeلإنشاء المفاتيح الخارجية أو حذفها، وapi.external_keys.readلعرض المفاتيح الخارجية أو استرجاعها أو التحقق من صحتها. ولا يحتاج المفتاح الواحد إلى كلا النطاقين إلا إذا كان يجب عليه تنفيذ عمليتي القراءة والكتابة.
الاستخدام
يتم تسجيل تكوين نظام 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 على مشروع جديد عبر واجهة برمجة تطبيقات الإدارة.
نوصي بإنشاء مشاريع جديدة لأعباء عمل نظام EKM لديك. يرجى ملاحظة أفضل الممارسات التالية قبل طرح نظام EKM على مشاريع الإنتاج الحالية لديك.
اختبر أولاً جميع ميزات واجهة API التي تستخدمها في بيئة الإنتاج في مشروع EKM API التجريبي.
قم بتطبيق طرح تدريجي بدلاً من تعبئة نظام EKM في جميع مشاريع واجهة API في بيئة الإنتاج دفعة واحدة.
نقطة النهاية على مستوى المنظمة
تسجيل مفتاح خارجي في منظمتك
AWS
مثال على طلب:
type: سلسلة نصية - دائمًا "aws"
name: سلسلة نصية - اسم سهل الاستخدام للتكوين الخاص بك
role_arn: سلسلة نصية - معرّف ARN للدور الذي ستتولاه OpenAI في الخدمة السحابية لديك
kms_arn: سلسلة نصية - نظام إدارة المفاتيح ARN للمفتاح الرئيسي الذي تقوم بإدارته
external_id: سلسلة نصية - معرّف منظمتك أو معرّف مشروع واجهة برمجة التطبيقات
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: سلسلة نصية - المجموعة التي تضم موفّر هوية عبء العمل الذي قمت بتسجيله لـ OpenAI
workload_identity_provider_id: سلسلة نصية - موفّر هوية عبء العمل الذي قمت بتسجيله لـ OpenAI
audience: سلسلة نصية - الجمهور الذي يجب على OpenAI تمريره في الرمز عند تولي دور من خلال GCP STS الخاص بك
kms_project_id: سلسلة نصية - اسم مشروع GCP الذي يوجد فيه نظام KMS الخاص بك
kms_key_ring_name: سلسلة نصية - حلقة مفاتيح نظام إدارة المفاتيح التي تحتوي على المفتاح الرئيسي الذي تقوم بإدارته
kms_key_name: سلسلة نصية - اسم المفتاح الرئيسي لنظام إدارة المفاتيح
kms_key_location: سلسلة نصية - المنطقة التي يوجد فيها المفتاح الرئيسي لنظام إدارة المفاتيح الخاص بك
إذا كان نظام KMS لديك موجود في مشروع GCP مختلف عن المشروع الذي سجّلت فيه هوية عبء العمل الخاصة بـ OpenAI، فتأكد من أن المشروع الذي يحتوي على هوية عبء العمل الخاصة بـ 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 لوحدة Tenant الخاصة بـ Azure.
vault_uri: سلسلة نصية - معرّف URI لمخزن Azure الذي يحتوي على المفتاح الرئيسي الذي تديره
key_name: سلسلة نصية - اسم المفتاح الرئيسي في مخزن مفاتيح Azure الذي تديره
يجب أن يكون بالتنسيق <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"
}معرّف OCI
يرجى إعداد مفتاح AES-256 مفعّل ومنح OpenAI صلاحية الوصول إليه. يجب أن يتضمن المفتاح علامة حرة الصيغة باسم openai_organization_id تكون قيمتها معرّف المؤسسة الخاص بك في OpenAI. وللاطلاع على خطوات الإعداد، راجع: تهيئة OCI Vault لإدارة المفاتيح المؤسسية.
مثال على طلب:
type: سلسلة نصية - دائمًا "oci"
purpose: سلسلة نصية - "ekm"؛ القيمة الافتراضية عند إغفاله
name: سلسلة نصية - اسم سهل الاستخدام للتكوين الخاص بك
region: سلسلة نصية - منطقة OCI التي تحتوي على خزنتك ومفتاحك
vault_ocid: سلسلة - معرّف OCID الكامل لخزنتك
key_ocid: سلسلة نصية - معرّف OCID الكامل لمفتاح AES-256 الخاص بك
لا تمرر key_version_ocid عند استخدام EKM.
curl -X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys" \
-d '{
"type": "oci",
"purpose": "ekm",
"name": "OCI EKM Config",
"region": "us-ashburn-1",
"vault_ocid": "<VAULT_OCID>",
"key_ocid": "<AES_KEY_OCID>"
}'مثال على الرد:
{
"id": "extkey_xxxx",
"object": "organization.external_key",
"created_at": 1746175499,
"api_project_ids": [],
"type": "oci",
"purpose": "ekm",
"name": "OCI EKM Config",
"region": "us-ashburn-1",
"vault_ocid": "<VAULT_OCID>",
"key_ocid": "<AES_KEY_OCID>"
}تعيد واجهة API رمز HTTP 200 عند النجاح. احفظ قيمة id التي تم إرجاعها واستخدمها بوصفها external_key_id عند إنشاء مشروع. تنطبق عمليات العرض والاسترجاع والتحقق من الصحة والحذف الحالية أيضًا على تسجيلات معرّف OCI.
لاسترداد PSP، استخدم تسجيلًا منفصلًا من نوع RSA-3072 مع الغرض: "psp_decryption" ومعرّف key_version_ocid مطابق تمامًا. عيّن psp_decryption_key_id على معرّف التسجيل المقابل له لدى OpenAI. تحتاج OpenAI فقط إلى صلاحية القراءة للبيانات الوصفية والمفاتيح العامة الخاصة بمفتاح RSA هذا. للاطلاع على الإعداد الكامل، راجع: إعداد المفاتيح غير المتماثلة - OCI Vault.
حذف مفتاح خارجي مسجل في منظمتك
ملاحظة: يُمنع الحذف ما دام هناك مشروع نشط أو مساحة عمل تستخدم هذا التسجيل. بالنسبة إلى EKM، قم أولًا بأرشفة مشروعات API المرتبطة؛ يظل تسجيل EKM المرتبط بمساحة عمل محميًا. لاستعادة PSP، استبدل psp_decryption_key_id أو امسحه في كل مشروع نشط يشير إلى التسجيل قبل حذفه. لا يؤدي حذف تسجيل OpenAI إلى حذف المفتاح السحابي.
مثال على طلب
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>"
}الحصول على المفاتيح الخارجية المسجّلة في منظمتك
من دون عامل تصفية حسب الغرض، تتضمن القائمة تسجيلات الاسترداد لكل من EKM وPSP. استخدم ?purpose=ekm أو ?purpose=psp_decryption لتصفية القائمة حسب الغرض.
مثال على طلب
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 لا يزال بإمكانه الوصول إلى مفتاحك السحابي.
عند استخدام EKM، تتحقق OpenAI من قدرتها على التشفير وفك التشفير باستخدام المفتاح. للاطلاع على تفاصيل الإلغاء وآلية التخزين المؤقت، راجع: إرشادات دورة استخدام المفتاح.
في حالة استرداد PSP، تسترجع OpenAI المفتاح العام للإصدار المسجل وتقارنه باللقطة المخزنة. لا يؤكد نجاح التحقق من الصحة أن هوية الاسترداد الخاصة بك قادرة على فك التشفير. لا يؤدي فشل التحقق من الصحة إلى إزالة لقطة المفتاح العام المخزنة أو استبدالها.
يؤدي استرجاع عملية تسجيل باستخدام GET إلى إرجاع التهيئة المخزنة، ولا يعيد التحقق من إمكانية الوصول إلى مفتاحك السحابي.
مثال على طلب
curl -X POST -H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys/extkey_xxx/validate"مثال على الرد
{
"status": "success"
}أو ظهر خطأ من مزود الخدمة السحابية.
نقطة النهاية على مستوى المشروع
إنشاء مشروع جديد باستخدام معرّف مفتاح خارجي
هذا مماثل لنقطة نهاية إنشاء مشروع الحالية، مع إضافة المعلمة 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 التجريبي.
قم بتطبيق طرح تدريجي بدلاً من تعبئة نظام 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
}