EKM (Kunci Eksternal) di Management API

Pelajari cara mengelola kunci eksternal untuk EKM menggunakan Management API.

Diperbarui: 31 minutes ago

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.write untuk membuat atau menghapus kunci eksternal, serta api.external_keys.read untuk mencantumkan, mengambil, atau memvalidasi kunci eksternal. Sebuah kunci memerlukan kedua cakupan hanya jika kunci tersebut harus melakukan operasi baca dan tulis.

Penggunaan

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.

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
}

Apakah artikel ini membantu?