สรุป

การเข้าถึง

• endpoint ของ EKM สามารถเข้าถึงได้ใน Management API ผ่าน Admin API Key https://platform.openai.com/settings/organization/admin-keys (อย่าใช้ API key ปกติ) Admin API key มีให้สำหรับ เจ้าขององค์กร

• ใช้ api.external_keys.write เพื่อสร้างหรือลบคีย์ภายนอก และ api.external_keys.read เพื่อแสดงรายการหรือตรวจสอบคีย์ภายนอก คีย์เดียวจะต้องมีทั้งสอง scope ก็ต่อเมื่อจำเป็นต้องทำทั้งการอ่านและการเขียน

• ขณะนี้เราจำเป็นต้องเปิดใช้ 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 ใน body ของ endpoint Create Project ที่มีอยู่เดิม https://api.openai.com/v1/organization/projects

ข้อจำกัด

• คุณต้องทดสอบ EKM กับโปรเจกต์ใหม่ผ่าน Management API ก่อน

• เราแนะนำให้สร้างโปรเจกต์ใหม่สำหรับเวิร์กโหลด EKM ของคุณ อย่างไรก็ตาม หากคุณต้องการใช้ EKM กับโปรเจกต์ที่มีอยู่แล้ว เราสามารถเพิ่มคุณเข้า feature flag ได้ โปรดทราบแนวทางปฏิบัติที่ดีที่สุดต่อไปนี้ก่อนที่คุณจะนำ EKM ไปใช้กับโปรเจกต์ production ที่มีอยู่ของคุณ

  • ทดสอบฟีเจอร์ API ทั้งหมดที่คุณใช้ใน production ในโปรเจกต์ EKM API สำหรับทดสอบของคุณก่อน

  • ทยอยเปิดใช้งานแทนการใส่ EKM ให้กับโปรเจกต์ API production ทั้งหมดพร้อมกัน

endpoint ระดับองค์กร

ลงทะเบียนคีย์ภายนอกในองค์กรของคุณ

AWS

ตัวอย่างคำขอ

• type: string - เป็น “aws” เสมอ

• name: string - ชื่อที่เข้าใจง่ายสำหรับการกำหนดค่าของคุณ

• role_arn: string - Role ARN ที่ OpenAI จะใช้ในคลาวด์ของคุณ

• kms_arn: string - ARN ของ Key Management System สำหรับคีย์หลักที่คุณจัดการ

• external_id: string - รหัสองค์กรหรือรหัสโปรเจกต์ 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 - pool ที่มี Workload Identity provider ที่คุณลงทะเบียนไว้สำหรับ OpenAI

• workload_identity_provider_id: string - Workload Identity provider ที่คุณลงทะเบียนไว้สำหรับ OpenAI

• audience: string - audience ที่ OpenAI ควรส่งใน Token เมื่อเรา assume role ผ่าน 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 tenant ของ Azure ของคุณ

• vault_uri: string - URI ของ Azure vault ที่มีคีย์หลักที่คุณจัดการ

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

ลบคีย์ภายนอกที่ลงทะเบียนไว้ในองค์กรของคุณ

หมายเหตุ: คุณสามารถลบคีย์ภายนอกได้ก็ต่อเมื่อคีย์นั้นไม่ได้เชื่อมโยงกับโปรเจกต์ที่ใช้งานอยู่ใดๆ หากเชื่อมโยงกับโปรเจกต์ที่ใช้งานอยู่ คุณต้อง archive โปรเจกต์นั้นก่อน

ตัวอย่างคำขอ

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 และจะมีผลหลังจาก cache TTL 1 ชั่วโมงหมดอายุแล้ว (คุณจะเห็นการตอบกลับแบบข้อผิดพลาด)

ตัวอย่างคำขอ

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

ตัวอย่างการตอบกลับ

{
 "status": "success"
}

หรืออาจเป็นข้อผิดพลาดที่มาจากผู้ให้บริการคลาวด์

endpoint ระดับโปรเจกต์

สร้างโปรเจกต์ใหม่พร้อมรหัสคีย์ภายนอก

เหมือนกับ 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,
}

[จำกัดการใช้งาน] อัปเดตโปรเจกต์ที่มีอยู่ด้วยรหัสคีย์ภายนอก

เหมือนกับ endpoint Update Project ที่มีอยู่เดิม โดยเพิ่มพารามิเตอร์ external_key_id ในคำขอและการตอบกลับ

เราแนะนำให้สร้างโปรเจกต์ API ใหม่สำหรับเวิร์กโหลด EKM ของคุณ หากคุณต้องการใช้ EKM กับโปรเจกต์ API ที่มีอยู่ทั้งหมดของคุณ โปรดติดต่อ account director ของคุณ แล้วเราจะเพิ่มคุณเข้า feature flag โปรดทราบแนวทางปฏิบัติที่ดีที่สุดต่อไปนี้ก่อนที่คุณจะนำ EKM ไปใช้กับโปรเจกต์ production ที่มีอยู่ของคุณ

• ทดสอบฟีเจอร์ API ทั้งหมดที่คุณใช้ใน production ในโปรเจกต์ EKM API สำหรับทดสอบของคุณก่อน

• ทยอยเปิดใช้งานแทนการใส่ EKM ให้กับโปรเจกต์ API production ทั้งหมดพร้อมกัน

ตัวอย่างคำขอ

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
}