خلاصه
دسترسی
نقطههای پایان EKM در 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، یک external_key_id به شکل extkey_xxxx برگردانده میشود.
پیکربندیهای EKM با ارسال external_key_id در بدنهٔ درخواست به نقطه پایان فعلیِ ایجاد پروژه، https://api.openai.com/v1/organization/projects، در سطح پروژه فعال میشوند.
محدودیتها
ابتدا باید EKM را از طریق API مدیریت در یک پروژهٔ جدید آزمایش کنید.
توصیه میکنیم برای بارهای کاری EKM خود پروژههای جدید ایجاد کنید. پیش از پیادهسازی EKM در پروژههای فعلی محیط عملیاتی، نکات زیر را برای اجرای بهتر در نظر بگیرید.
ابتدا تمام قابلیتهای API را که در محیط عملیاتی استفاده میکنید، در پروژهٔ API آزمایشیِ EKM خود آزمایش کنید.
بهجای فعالکردن یکبارهٔ EKM در تمام پروژههای API محیط عملیاتی، آن را بهتدریج پیادهسازی کنید.
endpointهای سطح سازمان
ثبت یک کلید خارجی در سازمان شما
AWS
نمونهٔ درخواست:
type: رشته - همیشه «aws»
name: رشته - نامی خوانا برای پیکربندی شما
role_arn: رشته - ARN نقشی که OpenAI در محیط ابری شما بر عهده میگیرد
kms_arn: رشته - ARN سامانهٔ مدیریت کلید برای کلید اصلیای که مدیریت میکنید
external_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: رشته - مخزنی که ارائهدهندهٔ هویت بار کاری ثبتشده برای 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 را در آن ثبت کردهاید، با مراجعه به https://console.developers.google.com/apis/api/cloudkms.googleapis.com/overview مطمئن شوید که دستکم KMS در پروژهٔ حاوی هویت بار کاری OpenAI فعال است.
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 شناسهٔ سازمان شما در 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 شما
برای 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 استفاده کنید. عملیات فعلیِ فهرستکردن، دریافت، اعتبارسنجی و حذف برای رکوردهای ثبتشدهٔ OCI نیز قابل استفادهاند.
برای بازیابی PSP، از یک رکورد ثبتشدهٔ جداگانهٔ RSA-3072 با purpose: "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>"
}دریافت کلیدهای خارجی ثبتشده در سازمان شما
بدون فیلتر purpose، فهرست شامل موارد ثبتشده برای 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"
}یا خطایی که از ارائهدهنده ابر نمایش داده شده است.
endpointهای سطح پروژه
ایجاد پروژهٔ جدید با شناسهٔ کلید خارجی
این نقطه پایان همان نقطه پایان فعلیِ ایجاد پروژه است، با این تفاوت که پارامتر 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 به درخواست و پاسخ اضافه شده است.
توصیه میکنیم برای بارهای کاری 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
}