OpenAI

EKM (Kunci Eksternal) di Management API

Kelola kunci eksternal untuk EKM menggunakan Management API

Diperbarui: 13 days ago

Ringkasan

Akses

  • Endpoint EKM dapat diakses di Management API melalui Kunci API Admin. https://platform.openai.com/settings/organization/admin-keys (jangan gunakan kunci API normal). 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 atau memvalidasi kunci eksternal. Sebuah kunci memerlukan kedua cakupan hanya jika kunci tersebut harus melakukan operasi baca dan tulis.

  • Saat ini kami perlu mengaktifkan fitur flag untuk organisasi Anda pada endpoint ini. Anda tahu bahwa Anda memiliki fitur flag tersebut jika Anda melihat **external_key_id **yang dikembalikan dari endpoint List Projects yang ada: https://api.openai.com/v1/organization/projects

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. Namun, jika Anda menginginkan EKM pada proyek yang sudah ada, kami dapat menambahkan Anda ke bendera fitur. Harap perhatikan praktik terbaik berikut sebelum Anda meluncurkan EKM ke proyek produksi yang sudah ada.

    • Uji semua fitur API yang Anda gunakan di bagian produksi terlebih dahulu di 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": <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

Permintaan Sampel

  • type: string - selalu  "gcp",

  • name: string - Nama yang mudah dikenali untuk konfigurasi Anda

  • workload_identity_project_number: string - Nomor proyek GCP 12 digit 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 project GCP yang berbeda dari project 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"
}

Hapuslah kunci eksternal yang terdaftar di organisasi Anda

Catatan: Anda hanya dapat menghapus kunci eksternal jika kunci tersebut tidak terkait dengan proyek aktif apa pun. Jika item tersebut terkait dengan proyek aktif, Anda harus mengarsipkan proyek tersebut terlebih dahulu.

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

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

Anda dapat menggunakan endpoint ini untuk memeriksa beberapa hal

  • Konfigurasi cloud eksternal Anda tetap valid dengan OpenAI setelah Anda membuat perubahan (Anda akan melihat respons berhasil)

  • Pencabutan kunci Anda telah dilakukan dengan benar, sedang diproses oleh OpenAI, dan akan berlaku setelah masa berlaku cache 1 jam berakhir (Anda akan melihat pesan kesalahan)

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": "Some Project",
   "external_key_id": "extkey_xxxx"
}'

Contoh Respons

{
  "object": "project",
  "id": "proj_xxxxx",
  "title": "Beberapa Proyek",
  "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,
}

[Restricted] 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. Jika Anda ingin EKM di semua proyek API Anda yang sudah ada, hubungi Direktur Akun Anda dan kami akan menambahkan Anda ke bendera fitur. Harap perhatikan praktik terbaik berikut sebelum Anda meluncurkan EKM ke proyek produksi yang sudah ada.

  • Uji semua fitur API yang Anda gunakan di bagian produksi terlebih dahulu di 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?