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 untuk pemilik organisasi.
Gunakan api.external_keys.write untuk mencipta atau memadamkan kunci luaran, dan api.external_keys.read untuk menyenaraikan atau mengesahkan kunci luaran. Sesuatu kunci hanya memerlukan kedua-dua skop jika kunci itu perlu melakukan operasi baca dan tulis.
Buat masa ini, kami perlu mengaktifkan bendera ciri untuk organisasi anda agar dapat mengakses titik akhir ini. Bendera ciri anda sudah aktif jika anda melihat external_key_id dikembalikan daripada titik akhir Senaraikan Projek yang sedia ada: https://api.openai.com/v1/organization/projects.

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 terlebih dahulu pada projek baharu melalui API Pengurusan.
Kami mengesyorkan agar anda mencipta projek baharu untuk beban kerja EKM anda. Walau bagaimanapun, jika anda mahu menggunakan EKM pada projek sedia ada, kami boleh mengaktifkan bendera ciri untuk anda. Sila ambil perhatian tentang amalan terbaik berikut sebelum melaksanakan EKM pada projek sedia ada anda dalam persekitaran pengeluaran.
- Uji dahulu semua ciri API yang anda gunakan dalam persekitaran pengeluaran pada projek API EKM ujian anda.
- Laksanakan secara berperingkat dan bukannya mengaktifkan EKM pada semua projek API dalam persekitaran 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"
}

Padamkan kunci luaran yang didaftarkan dalam organisasi anda

Nota: Anda hanya boleh memadamkan kunci luaran jika kunci itu tidak dikaitkan dengan mana-mana projek API atau ruang kerja yang aktif. Jika kunci itu dikaitkan dengan projek API yang aktif, arkibkan projek tersebut terlebih dahulu. Jika kunci itu dikaitkan dengan ruang kerja, kunci tersebut tidak boleh dipadamkan.

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 dalam organisasi anda

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

Anda boleh menggunakan titik akhir ini untuk menyemak beberapa perkara:

Konfigurasi awan luaran anda kekal sah untuk digunakan dengan OpenAI selepas anda membuat perubahan (anda akan melihat respons berjaya).
Pembatalan kunci anda dilakukan dengan betul, sedang diproses oleh OpenAI dan akan berkuat kuasa selepas TTL cache selama 1 jam tamat (anda akan melihat respons ralat).

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"
}

[Terhad] Kemas kini projek sedia ada dengan ID kunci luaran

Titik akhir ini sama seperti titik akhir Kemas Kini Projek yang sedia ada, tetapi dengan penambahan parameter external_key_id dalam permintaan dan respons.

Kami mengesyorkan agar anda mencipta projek API baharu untuk beban kerja EKM anda. Jika anda mahu menggunakan EKM pada semua projek API sedia ada anda, hubungi pengarah akaun anda dan kami akan mengaktifkan bendera ciri untuk anda. Sila ambil perhatian tentang amalan terbaik berikut sebelum melaksanakan EKM pada projek sedia ada anda dalam persekitaran pengeluaran.

Uji dahulu semua ciri API yang anda gunakan dalam persekitaran pengeluaran pada projek API EKM ujian anda.
Laksanakan secara berperingkat dan bukannya mengaktifkan EKM pada semua projek API dalam persekitaran 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
}

EKM (Kunci Luaran) dalam API Pengurusan

Ringkasan

Akses

Penggunaan

Sekatan

Titik akhir peringkat organisasi

Daftarkan kunci luaran pada organisasi anda

AWS

GCP

Azure

Padamkan kunci luaran yang didaftarkan dalam organisasi anda

Contoh permintaan

Contoh respons

Dapatkan kunci luaran yang didaftarkan dalam organisasi anda

Contoh permintaan

Contoh respons

Sahkan kunci luaran

Contoh permintaan

Contoh respons

Titik akhir peringkat projek

Cipta projek baharu dengan ID kunci luaran

Contoh permintaan

Contoh respons

[Terhad] Kemas kini projek sedia ada dengan ID kunci luaran

Contoh permintaan

Senaraikan semua projek dalam organisasi anda

Contoh permintaan

Contoh respons

Adakah artikel ini membantu?