Ringkasan
Akses
Titik akhir EKM boleh diakses dalam API Pengurusan menggunakan Kunci API Pentadbir. https://platform.openai.com/settings/organization/admin-keys (jangan gunakan kunci API biasa). Kunci API pentadbir tersedia kepada pemilik organisasi.
Gunakan
api.external_keys.writeuntuk mencipta atau memadam kunci luaran, danapi.external_keys.readuntuk menyenaraikan, mendapatkan atau mengesahkan kunci luaran. Sesuatu kunci hanya memerlukan kedua-dua skop jika kunci itu perlu menjalankan operasi baca dan tulis.
Penggunaan
Konfigurasi EKM anda didaftarkan pada peringkat organisasi melalui titik akhir baharu https://api.openai.com/v1/organization/external_keys.
Pendaftaran konfigurasi EKM anda mengembalikan external_key_id dalam bentuk extkey_xxxx.
Konfigurasi EKM diaktifkan pada peringkat projek dengan menyertakan external_key_id dalam badan permintaan kepada titik akhir Cipta Projek yang sedia ada, https://api.openai.com/v1/organization/projects.
Sekatan
Anda mesti menguji EKM pada projek baharu terlebih dahulu melalui API Pengurusan.
Kami mengesyorkan agar anda menyediakan projek baharu untuk beban kerja EKM anda. Sila ambil perhatian tentang amalan terbaik berikut sebelum melaksanakan EKM pada projek pengeluaran sedia ada anda.
Uji dahulu semua ciri API yang anda gunakan dalam persekitaran pengeluaran dalam projek API EKM ujian anda.
Laksanakan EKM secara berperingkat, bukannya pada semua projek API pengeluaran serentak.
Titik akhir peringkat organisasi
Daftarkan kunci luaran pada organisasi anda
AWS
Contoh permintaan:
type: rentetan - sentiasa “aws”
name: rentetan - Nama yang mudah dikenali untuk konfigurasi anda
role_arn: rentetan - ARN peranan yang akan digunakan oleh OpenAI dalam awan anda
kms_arn: rentetan - ARN Sistem Pengurusan Kunci untuk kunci induk yang anda urus
external_id: rentetan - ID Organisasi atau ID projek API anda
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>"
}'Contoh respons:
{
"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
Contoh permintaan:
type: rentetan - sentiasa "gcp",
name: rentetan - Nama yang mudah dikenali untuk konfigurasi anda
workload_identity_project_number: rentetan - Nombor projek GCP dalam bentuk angka tempat anda mendaftarkan identiti beban kerja OpenAI
workload_identity_pool_id: rentetan - Kumpulan yang mengandungi penyedia Workload Identity yang anda daftarkan untuk OpenAI
workload_identity_provider_id: rentetan - Penyedia Workload Identity yang anda daftarkan untuk OpenAI
audience: rentetan - Penerima sasaran yang perlu disertakan oleh OpenAI dalam token apabila kami menggunakan sesuatu peranan melalui GCP STS anda
kms_project_id: rentetan - Nama projek GCP tempat KMS anda berada
kms_key_ring_name: rentetan - Gelang kunci Sistem Pengurusan Kunci yang mengandungi kunci induk yang anda urus
kms_key_name: rentetan - Nama kunci induk Sistem Pengurusan Kunci
kms_key_location: rentetan - Rantau tempat kunci induk Sistem Pengurusan Kunci anda berada
Jika KMS anda berada dalam projek GCP yang berbeza daripada projek tempat anda mendaftarkan Workload Identity OpenAI, pastikan sekurang-kurangnya KMS telah didayakan untuk projek yang mengandungi Workload Identity OpenAI dengan melawati 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"
}'Contoh respons:
{
"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
Contoh permintaan:
type: rentetan - sentiasa "azure",
name: rentetan - Nama yang mudah dikenali untuk konfigurasi anda
tenant_id: rentetan - UUID penyewa Azure anda
vault_uri: rentetan - URI peti simpanan Azure yang mengandungi kunci induk yang anda urus
key_name: rentetan - Nama kunci induk Azure Key Vault yang anda urus.
Nama ini mesti mengikut format <org-xxx>--<any_name>
dengan org-xxx ialah ID Organisasi OpenAI anda yang boleh anda temukan di 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"
}'Contoh respons:
{
"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
Sediakan kunci AES-256 yang diaktifkan dan berikan akses kepada OpenAI. Kunci tersebut mesti mempunyai tag bentuk bebas openai_organization_id yang ditetapkan kepada ID Organisasi OpenAI anda. Untuk langkah persediaan, lihat: Mengkonfigurasi OCI Vault untuk Pengurusan Kunci Perusahaan.
Contoh permintaan:
type: rentetan - sentiasa "oci"
purpose: rentetan - "ekm"; nilai lalai jika tidak dinyatakan
name: rentetan - Nama yang mudah dikenali untuk konfigurasi anda
region: rentetan - Rantau OCI yang menempatkan peti besi dan kunci anda
vault_ocid: rentetan - OCID penuh peti besi anda
key_ocid: rentetan - OCID penuh kunci AES-256 anda
Jangan sertakan key_version_ocid untuk EKM.
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>"
}'Contoh respons:
{
"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 mengembalikan HTTP 200 apabila berjaya. Simpan id yang dikembalikan dan gunakannya sebagai external_key_id semasa mencipta projek. Operasi sedia ada untuk menyenaraikan, mendapatkan, mengesahkan dan memadam juga terpakai pada pendaftaran OCI.
Untuk pemulihan PSP, gunakan pendaftaran RSA-3072 berasingan dengan purpose: "psp_decryption" dan nilai key_version_ocid yang tepat. Tetapkan psp_decryption_key_id kepada ID pendaftaran OpenAI bagi kunci tersebut. OpenAI hanya memerlukan akses baca kepada metadata dan kunci awam bagi kunci RSA tersebut. Untuk persediaan lengkap, lihat: Sediakan kunci asimetri — OCI Vault.
Padam kunci luaran yang didaftarkan untuk organisasi anda
Nota: Pemadaman disekat selagi projek atau ruang kerja yang aktif menggunakan pendaftaran tersebut. Untuk EKM, arkibkan projek API yang berkaitan terlebih dahulu; pendaftaran EKM yang dikaitkan dengan ruang kerja kekal dilindungi. Untuk pemulihan PSP, gantikan atau kosongkan psp_decryption_key_id pada setiap projek aktif yang merujuk kepada pendaftaran tersebut sebelum memadamkannya. Memadam pendaftaran OpenAI tidak akan memadam kunci awan.
Contoh permintaan
curl -X DELETE \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys/extkey_xxxx"Contoh respons
{
"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>"
}Dapatkan kunci luaran yang didaftarkan untuk organisasi anda
Tanpa penapis tujuan, senarai ini merangkumi pendaftaran EKM dan pemulihan PSP. Gunakan ?purpose=ekm atau ?purpose=psp_decryption untuk menapis mengikut tujuan.
Contoh permintaan
curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys"Contoh respons
{
"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"
}Sahkan kunci luaran
Gunakan pengesahan untuk menyemak sama ada OpenAI masih boleh mengakses kunci awan anda.
Untuk EKM, OpenAI menyemak sama ada penyulitan dan penyahsulitan boleh dilakukan menggunakan kunci tersebut. Untuk cara pembatalan dan caching berfungsi, lihat: panduan kitar hayat kunci.
Untuk pemulihan PSP, OpenAI mendapatkan kunci awam bagi versi yang didaftarkan dan membandingkannya dengan petikan keadaan yang disimpan. Pengesahan yang berjaya tidak mengesahkan bahawa identiti pemulihan anda boleh melakukan penyahsulitan. Pengesahan yang gagal tidak mengalih keluar atau menggantikan petikan keadaan kunci awam yang disimpan.
Mendapatkan pendaftaran menggunakan GET akan mengembalikan konfigurasi yang disimpan tanpa menyemak semula akses kepada kunci awan anda.
Contoh permintaan
curl -X POST -H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys/extkey_xxx/validate"Contoh respons
{
"status": "success"
}Atau, ralat yang dikemukakan daripada penyedia awan.
Titik akhir peringkat projek
Cipta projek baharu dengan ID kunci luaran
Titik akhir ini sama seperti titik akhir Cipta Projek yang sedia ada, tetapi dengan penambahan parameter external_key_id dalam permintaan dan respons.
Contoh permintaan
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"
}'Contoh respons
{
"object": "organization.project",
"id": "proj_xxxxx",
"name": "Some Project",
"external_key_id": "extkey_xxxx",
"created_at": 1740012721,
"archived_at": null,
"status": "active"
}Kemas kini projek sedia ada dengan ID kunci luaran
Ini sama seperti titik akhir Kemas Kini Projek sedia ada, dengan penambahan parameter external_key_id dalam permintaan dan respons.
Kami mengesyorkan agar anda menyediakan projek API baharu untuk beban kerja EKM anda. Sila ambil perhatian tentang amalan terbaik berikut sebelum melaksanakan EKM pada projek pengeluaran sedia ada anda.
Uji dahulu semua ciri API yang anda gunakan dalam persekitaran pengeluaran dalam projek API EKM ujian anda.
Laksanakan EKM secara berperingkat, bukannya pada semua projek API pengeluaran serentak.
Contoh permintaan
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"
}'Senaraikan semua projek dalam organisasi anda
Titik akhir ini sama seperti titik akhir sedia ada, tetapi dengan penambahan external_key_id dalam respons API.
Contoh permintaan
curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/projects"Contoh respons
{
"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
}