Ringkasan
Akses
Endpoint EKM dapat diakses di Management API melalui Kunci API Admin. https://platform.openai.com/settings/organization/admin-keys (jangan menggunakan kunci API biasa). Kunci Admin API tersedia untuk pemilik organisasi.
Gunakan
api.external_keys.writeuntuk membuat atau menghapus kunci eksternal, sertaapi.external_keys.readuntuk mencantumkan, mengambil, atau memvalidasi kunci eksternal. Sebuah kunci memerlukan kedua cakupan hanya jika kunci tersebut harus melakukan operasi baca dan tulis.
Penggunaan
Konfigurasi EKM Anda terdaftar di tingkat organisasi melalui endpoint baru https://api.openai.com/v1/organization/external_keys.
Mendaftarkan konfigurasi EKM Anda mengembalikan external_key_id dalam bentuk extkey_xxxx.
Konfigurasi EKM diaktifkan pada level proyek dengan meneruskan external_key_id dalam isi permintaan Create Project yang ada https://api.openai.com/v1/organization/projects endpoint.
Pembatasan
Anda harus menguji EKM pada proyek baru melalui Management API terlebih dahulu.
Kami menyarankan Anda untuk membuat proyek baru untuk beban kerja EKM Anda. Harap perhatikan praktik terbaik berikut sebelum Anda meluncurkan EKM ke proyek produksi yang sudah ada.
Uji terlebih dahulu semua fitur API yang Anda gunakan di lingkungan produksi pada proyek API EKM pengujian Anda.
Terapkan peluncuran bertahap alih-alih mengisi EKM di semua proyek API produksi sekaligus.
Endpoint tingkat organisasi
Daftarkan kunci eksternal di organisasi Anda
AWS
Permintaan sampel:
tipe: string - selalu “aws”
name: string - Nama yang mudah dikenali untuk konfigurasi Anda
role_arn: string - Peran ARN yang akan digunakan OpenAI di cloud milik Anda
kms_arn: string - ARN Sistem Manajemen Kunci untuk kunci master yang Anda kelola
external_id: string - ID Organisasi Anda atau ID proyek 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": "<id org atau id proyek Anda>"
}'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
Permintaan sampel:
type: string - selalu "gcp",
name: string - Nama yang mudah dikenali untuk konfigurasi Anda
workload_identity_project_number: string - Nomor proyek GCP numerik tempat Anda mendaftarkan identitas workload OpenAI
workload_identity_pool_id: string - Pool yang berisi penyedia Workload Identity yang Anda daftarkan untuk OpenAI
workload_identity_provider_id: string - Penyedia Workload Identity yang Anda daftarkan di OpenAI
audiens: string - Audiens yang harus diteruskan OpenAI dalam token saat kami mengasumsikan peran melalui GCP STS Anda
kms_project_id: string - Nama proyek GCP tempat KMS Anda berada
kms_key_ring_name: string - Gugus kunci pada Sistem Manajemen Kunci yang berisi kunci master yang Anda kelola
kms_key_name: string - Nama kunci utama Sistem Manajemen Kunci
kms_key_location: string - Wilayah tempat kunci master Sistem Manajemen Kunci Anda berada
Jika KMS Anda berada di proyek GCP yang berbeda dari proyek tempat Anda mendaftarkan Identitas Beban Kerja OpenAI, pastikan bahwa proyek yang berisi Identitas Beban Kerja OpenAI setidaknya telah mengaktifkan KMS dengan membuka 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
Permintaan sampel:
type: string - selalu "azure",
name: string - Nama yang mudah dikenali untuk konfigurasi Anda
tenant_id: string - UUID tenant Azure Anda
vault_uri: string - URI dari Azure vault yang berisi kunci master yang Anda kelola
key_name: string - Nama kunci master Azure Key Vault yang Anda kelola.
Harus berbentuk <org-xxx>--<any_name>
di mana org-xxx adalah ID organisasi OpenAI Anda yang dapat ditemukan 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
Siapkan kunci AES-256 yang aktif dan berikan akses kepada OpenAI. Kunci tersebut harus memiliki tag openai_organization_id berformat bebas yang diatur ke ID Organisasi OpenAI Anda. Untuk langkah-langkah penyiapan, lihat: Mengonfigurasi OCI Vault untuk Manajemen Kunci Enterprise.
Permintaan sampel:
tipe: string - selalu "oci"
tujuan: string - "ekm"; default jika tidak dicantumkan
name: string - Nama yang mudah dikenali untuk konfigurasi Anda
wilayah: string - Wilayah OCI yang berisi vault dan kunci Anda
vault_ocid: string - OCID lengkap vault Anda
key_ocid: string - OCID lengkap kunci AES-256 Anda
Jangan berikan 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 jika berhasil. Simpan id yang dikembalikan dan gunakan sebagai external_key_id saat membuat proyek. Operasi list, retrieve, validate, dan delete yang sudah ada juga berlaku untuk registrasi OCI.
Untuk pemulihan PSP, gunakan pendaftaran RSA-3072 terpisah dengan tujuan: "psp_decryption" dan key_version_ocid yang persis. Atur psp_decryption_key_id ke ID pendaftaran OpenAI tersebut. OpenAI hanya memerlukan akses baca ke metadata dan kunci publik untuk kunci RSA tersebut. Untuk penyiapan lengkap, lihat: Menyiapkan kunci asimetris — OCI Vault.
Hapuslah kunci eksternal yang terdaftar di organisasi Anda
Catatan: Penghapusan diblokir selama proyek aktif atau workspace menggunakan pendaftaran. Untuk EKM, arsipkan proyek API terkait terlebih dahulu; pendaftaran EKM yang terkait dengan workspace tetap dilindungi. Untuk pemulihan PSP, ganti atau kosongkan psp_decryption_key_id pada setiap proyek aktif yang merujuk ke pendaftaran tersebut sebelum menghapusnya. Menghapus pendaftaran OpenAI tidak menghapus kunci cloud.
Permintaan sampel
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 eksternal yang terdaftar di organisasi Anda
Tanpa filter tujuan, daftar mencakup registrasi pemulihan EKM dan PSP. Gunakan ?purpose=ekm atau ?purpose=psp_decryption untuk memfilter berdasarkan tujuan.
Permintaan sampel
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"
}Validasi kunci eksternal
Gunakan validasi untuk memeriksa apakah OpenAI masih dapat mengakses kunci cloud Anda.
Untuk EKM, OpenAI memeriksa apakah OpenAI dapat mengenkripsi dan mendekripsi menggunakan kunci. Untuk perilaku pencabutan dan penyimpanan dalam cache, lihat: panduan siklus hidup kunci.
Untuk pemulihan PSP, OpenAI mengambil kunci publik dari versi terdaftar dan membandingkannya dengan snapshot yang tersimpan. Validasi yang berhasil tidak memastikan bahwa identitas pemulihan Anda dapat melakukan dekripsi. Validasi yang gagal tidak menghapus atau mengganti snapshot kunci publik yang tersimpan.
Mengambil registrasi dengan GET mengembalikan konfigurasi yang tersimpan dan tidak memeriksa ulang akses ke kunci cloud Anda.
Permintaan sampel
curl -X POST -H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys/extkey_xxx/validate"Contoh respons
{
"status": "success"
}Atau, terjadi kesalahan dari penyedia cloud.
Endpoint level proyek
Buat proyek baru dengan ID kunci eksternal
Ini sama dengan endpoint Buat Proyek yang sudah ada, dengan penambahan parameter external_key_id dalam permintaan dan respons.
Permintaan sampel
curl -X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/projects" \
-d '{
"name": "Beberapa Proyek",
"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"
}Perbarui proyek yang sudah ada dengan ID kunci eksternal
Ini sama dengan endpoint Update Project yang ada, dengan penambahan parameter external_key_id dalam permintaan dan respons.
Kami menyarankan Anda membuat proyek API baru untuk beban kerja EKM Anda. Harap perhatikan praktik terbaik berikut sebelum Anda meluncurkan EKM ke proyek produksi yang sudah ada.
Uji terlebih dahulu semua fitur API yang Anda gunakan di lingkungan produksi pada proyek API EKM pengujian Anda.
Terapkan peluncuran bertahap alih-alih mengisi EKM di semua proyek API produksi sekaligus.
Permintaan sampel
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"
}'Tampilkan semua proyek di organisasi Anda
Ini sama dengan endpoint yang ada tetapi dengan penambahan external_key_id di respons API.
Permintaan sampel
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
}