สรุป
การเข้าถึง
endpoint ของ 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 ให้องค์กรของคุณเพื่อใช้ endpoint เหล่านี้ คุณจะทราบว่ามี 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 ทั้งหมดที่คุณใช้ในโปรดักชันในโปรเจกต์ API สำหรับทดสอบ EKM ของคุณก่อน
ทยอยเปิดตัวอย่างค่อยเป็นค่อยไปแทนการเพิ่ม EKM ลงในโปรเจกต์ API โปรดักชันทั้งหมดพร้อมกัน
endpoint ระดับองค์กร
ลงทะเบียนคีย์ภายนอกในองค์กรของคุณ
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 - หมายเลขโปรเจกต์ GCP 12 หลักที่คุณลงทะเบียน 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 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 ของคุณ
vault_uri: string - URI ของ Azure vault ที่มีมาสเตอร์คีย์ที่คุณจัดการ
key_name: string - ชื่อของมาสเตอร์คีย์ Azure Key Vault ที่คุณจัดการ
ต้องอยู่ในรูปแบบ <org-xxx>--<any_name>
โดยที่ org-xxx คือ ID องค์กร 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"
}ลบคีย์ภายนอกที่ลงทะเบียนไว้ในองค์กรของคุณ
หมายเหตุ: คุณสามารถลบคีย์ภายนอกได้เฉพาะเมื่อคีย์นั้นไม่ได้เชื่อมโยงกับโปรเจกต์ 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 และจะมีผลหลังจากแคช TTL 1 ชั่วโมงหมดอายุ (คุณจะเห็นการตอบกลับข้อผิดพลาด)
ตัวอย่างคำขอ
curl -X POST -H "Authorization: Bearer $TOKEN"
"https://api.openai.com/v1/organization/external_keys/extkey_xxx/validate"ตัวอย่างการตอบกลับ
{
"status": "success"
}หรือข้อผิดพลาดที่ส่งขึ้นมาจากผู้ให้บริการคลาวด์
endpoint ระดับโปรเจกต์
สร้างโปรเจกต์ใหม่ด้วย 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 ที่มีอยู่ทั้งหมด ให้สอบถามผู้อำนวยการบัญชีของคุณ แล้วเราจะเพิ่มคุณใน feature flag โปรดทราบแนวทางปฏิบัติที่ดีที่สุดต่อไปนี้ก่อนเปิดตัว 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"
}'แสดงรายการโปรเจกต์ทั้งหมดในองค์กรของคุณ
เหมือนกับ 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
}