เรียนรู้วิธีจัดการคีย์ภายนอกสำหรับ EKM โดยใช้ Management API

สรุป

การเข้าถึง

คุณสามารถเข้าถึง endpoint ของ EKM ใน Management API โดยใช้คีย์ API ของผู้ดูแลระบบ https://platform.openai.com/settings/organization/admin-keys (อย่าใช้คีย์ API ทั่วไป) เจ้าขององค์กรสามารถใช้คีย์ API ของผู้ดูแลระบบได้
ใช้ api.external_keys.write เพื่อสร้างหรือลบคีย์ภายนอก และใช้ api.external_keys.read เพื่อแสดงรายการหรือตรวจสอบความถูกต้องของคีย์ภายนอก คีย์หนึ่งคีย์จำเป็นต้องมีขอบเขตสิทธิ์ทั้งสองเฉพาะเมื่อต้องดำเนินการทั้งอ่านและเขียนเท่านั้น
ขณะนี้เราต้องเปิดใช้แฟล็กฟีเจอร์ให้องค์กรของคุณก่อน จึงจะเข้าถึง endpoint เหล่านี้ได้ คุณจะทราบว่าได้เปิดใช้แฟล็กฟีเจอร์แล้ว หากเห็น external_key_id ในผลลัพธ์ที่ส่งกลับจาก endpoint แสดงรายการโปรเจกต์ที่มีอยู่: 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 สร้างโปรเจกต์ที่มีอยู่ https://api.openai.com/v1/organization/projects

ข้อจำกัด

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

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

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

AWS

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

type: string - เป็น “aws” เสมอ
name: string - ชื่อที่เข้าใจง่ายสำหรับการกำหนดค่าของคุณ
role_arn: string - ARN ของบทบาทที่ OpenAI จะสวมสิทธิ์ในคลาวด์ของคุณ
kms_arn: string - ARN ในระบบจัดการคีย์ของคีย์หลักที่คุณจัดการ
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 ที่คุณลงทะเบียน 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 - คีย์ริงในระบบจัดการคีย์ที่มีคีย์หลักซึ่งคุณจัดการอยู่
kms_key_name: string - ชื่อคีย์หลักในระบบจัดการคีย์
kms_key_location: string - ภูมิภาคที่เก็บคีย์หลักในระบบจัดการคีย์ของคุณ

หาก KMS ของคุณอยู่ในโปรเจกต์ GCP คนละโปรเจกต์กับที่ลงทะเบียน Workload Identity ของ OpenAI ไว้ โปรดตรวจสอบว่าอย่างน้อยได้เปิดใช้ KMS ในโปรเจกต์ที่มี Workload Identity ของ OpenAI แล้ว โดยไปที่ 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 ของ vault ใน Azure ที่เก็บคีย์หลักที่คุณจัดการ
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"
}

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

หมายเหตุ: คุณจะลบคีย์ภายนอกได้ก็ต่อเมื่อคีย์นั้นไม่ได้เชื่อมโยงกับโปรเจกต์ 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 ระดับโปรเจกต์

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

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

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

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

เราขอแนะนำให้สร้างโปรเจกต์ API ใหม่สำหรับเวิร์กโหลด EKM ของคุณ หากคุณต้องการใช้ 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"
}'

แสดงรายการโปรเจกต์ทั้งหมดในองค์กรของคุณ

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

EKM (คีย์ภายนอก) ใน Management API

สรุป

การเข้าถึง

การใช้งาน

ข้อจำกัด

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

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

AWS

GCP

Azure

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

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

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

ดึงข้อมูลคีย์ภายนอกที่ลงทะเบียนไว้กับองค์กรของคุณ

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

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

ตรวจสอบความถูกต้องของคีย์ภายนอก

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

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

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

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

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

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

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

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

แสดงรายการโปรเจกต์ทั้งหมดในองค์กรของคุณ

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

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

บทความนี้มีประโยชน์หรือไม่