सारांश
एक्सेस
EKM एंडपॉइंट Management API में एडमिन 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 कॉन्फ़िगरेशन को रजिस्टर करने पर extkey_xxxx के रूप में एक external_key_id प्राप्त होता है.
EKM कॉन्फ़िगरेशन मौजूदा Create Project https://api.openai.com/v1/organization/projects के बॉडी में external_key_id पास करके प्रोजेक्ट स्तर पर सक्रिय किए जाते हैं. एंडपॉइंट.
प्रतिबंध
आपको पहले Management API के ज़रिए EKM को नए प्रोजेक्ट पर टेस्ट करना होगा.
हम आपके EKM वर्कलोड्स के लिए नए प्रोजेक्ट शुरू करने की सलाह देते हैं. कृपया अपने मौजूदा प्रोडक्शन प्रोजेक्ट्स में EKM लागू करने से पहले निम्नलिखित सर्वोत्तम प्रथाओं पर ध्यान दें.
प्रोडक्शन में जिन सभी API फीचर्स का आप उपयोग करते हैं, उन्हें पहले अपने टेस्ट EKM API प्रोजेक्ट में जांचें.
सभी प्रोडक्शन API प्रोजेक्ट्स में EKM को एक साथ पॉप्युलेट करने के बजाय क्रमिक रोलआउट को लागू करें.
संगठन-स्तरीय एंडपॉइंट
अपने संगठन में एक बाहरी कुंजी पंजीकृत करें
AWS
नमूना अनुरोध:
प्रकार: string - always “aws”
name: string - आपके कॉन्फ़िगरेशन के लिए एक सुविधाजनक नाम
role_arn: string - वह Role ARN जिसे OpenAI आपके क्लाउड में उपयोग करेगा
kms_arn: स्ट्रिंग - आपके द्वारा प्रबंधित मास्टर कुंजी के लिए Key Management System ARN
external_id: string - संगठन या API प्रोजेक्ट की 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
नमूना अनुरोध:
प्रकार: string - always "gcp",
name: string - आपके कॉन्फ़िगरेशन के लिए एक सुविधाजनक नाम
workload_identity_project_number: string - वह संख्यात्मक GCP प्रोजेक्ट नंबर जहां आपने OpenAI की वर्कलोड आइडेंटिटी पंजीकृत की थी
workload_identity_pool_id: स्ट्रिंग - वह पूल जिसमें वह वर्कलोड आइडेंटिटी प्रोवाइडर शामिल है जिसे आपने OpenAI के लिए रजिस्टर किया है
workload_identity_provider_id: स्ट्रिंग - वह वर्कलोड आइडेंटिटी प्रोवाइडर जिसे आपने OpenAI के लिए रजिस्टर किया है.
audience: string - वह ऑडियंस जिसे OpenAI आपके GCP STS के माध्यम से किसी भूमिका को अस्यूम करते समय टोकन में पास करना चाहिए
kms_project_id: स्ट्रिंग - वह GCP प्रोजेक्ट का नाम जहां आपका KMS मौजूद है
kms_key_ring_name: string - वह Key Management System कुंजी रिंग जिसमें वह मास्टर कुंजी शामिल है जिसे आप प्रबंधित करते हैं
kms_key_name: स्ट्रिंग - की मैनेजमेंट सिस्टम मास्टर कुंजी का नाम
kms_key_location: स्ट्रिंग - वह क्षेत्र जहाँ आपकी की मैनेजमेंट सिस्टम मास्टर कुंजी स्थित है
यदि आपका KMS उस GCP प्रोजेक्ट से अलग किसी अन्य GCP प्रोजेक्ट में है, जहाँ आपने OpenAI की Workload Identity को रजिस्टर किया है, तो https://console.developers.google.com/apis/api/cloudkms.googleapis.com/overview पर जाकर यह सुनिश्चित करें कि जिस प्रोजेक्ट में OpenAI की Workload Identity है, उसमें कम से कम KMS सक्षम हो.
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
नमूना अनुरोध:
प्रकार: string - always "azure",
name: string - आपके कॉन्फ़िगरेशन के लिए एक सुविधाजनक नाम
tenant_id: string - आपके Azure टेनेंट का UUID
vault_uri: string - आपके द्वारा प्रबंधित मास्टर कुंजी वाले Azure vault का URI
key_name: string - Azure Key Vault मास्टर कुंजी का नाम, जिसे तुम प्रबंधित करते हो.
यह <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 को एक्सेस दें. की में एक free-form openai_organization_id टैग सेट होना चाहिए, जिसमें आपका OpenAI ऑर्गनाइज़ेशन ID हो. सेटअप के चरणों के लिए, देखें: Enterprise Key Management के लिए OCI Vault कॉन्फ़िगर करना.
नमूना अनुरोध:
प्रकार: स्ट्रिंग - always "oci"
उद्देश्य: स्ट्रिंग - "ekm"; छोड़े जाने पर डिफ़ॉल्ट
name: string - आपके कॉन्फ़िगरेशन के लिए एक सुविधाजनक नाम
region: स्ट्रिंग - वह OCI क्षेत्र जिसमें आपका वॉल्ट और कुंजी मौजूद हैं
vault_ocid: स्ट्रिंग - आपके वॉल्ट का पूरा OCID
key_ocid: स्ट्रिंग - आपकी AES-256 की का पूरा OCID
EKM के लिए key_version_ocid पास न करें.
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 के रूप में इस्तेमाल करें. मौजूदा list, retrieve, validate और delete ऑपरेशन OCI पंजीकरणों पर भी लागू होते हैं.
PSP recovery के लिए, purpose: "psp_decryption" और exact key_version_ocid के साथ एक अलग RSA-3072 रजिस्ट्रेशन का उपयोग करें. psp_decryption_key_id को उसके OpenAI रजिस्ट्रेशन ID पर सेट करें. OpenAI को उस RSA kr के मेटाडेटा और पब्लिक कीज़ के लिए केवल रीड ऐक्सेस चाहिए. पूरे सेटअप के लिए, देखें: असममित krp] सेट अप करें — 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"
}या, क्लाउड प्रोवाइडर से कोई त्रुटि सामने आई.
प्रोजेक्ट-लेवल एंडपॉइंट
बाहरी कुंजी 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": "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 के साथ अपडेट करें
यह मौजूदा Update Project एंडपॉइंट के समान है, जिसमें अनुरोध और रिस्पॉन्स में external_key_id पैरामीटर जोड़ा गया है.
हम आपके EKM वर्कलोड्स के लिए नए API प्रोजेक्ट्स शुरू करने की सिफारिश करते हैं. कृपया अपने मौजूदा प्रोडक्शन प्रोजेक्ट्स में EKM लागू करने से पहले निम्नलिखित सर्वोत्तम प्रथाओं पर ध्यान दें.
प्रोडक्शन में जिन सभी API फीचर्स का आप उपयोग करते हैं, उन्हें पहले अपने टेस्ट EKM API प्रोजेक्ट में जांचें.
सभी प्रोडक्शन API प्रोजेक्ट्स में EKM को एक साथ पॉप्युलेट करने के बजाय क्रमिक रोलआउट को लागू करें.
नमूना अनुरोध
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"
}'अपने ऑर्गनाइजेशन के सभी प्रोजेक्ट्स की सूची दिखाएँ.
यह मौजूदा एंडपॉइंट जैसा ही है, लेकिन API रेस्पॉन्स में external_key_id जोड़ा गया है.
नमूना अनुरोध
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
}