Ringkesan
Akses
Titik pungkasan EKM bisa diakses ing API Manajemen nganggo Kunci API Admin. https://platform.openai.com/settings/organization/admin-keys (aja nganggo kunci API biasa). Kunci API Admin kasedhiya kanggo pamilik organisasi.
Gunakake
api.external_keys.writekanggo nggawe utawa mbusak kunci eksternal, lanapi.external_keys.readkanggo ndeleng dhaptar, njupuk, utawa validasi kunci eksternal. Siji kunci mung mbutuhake loro cakupan ijin kasebut yen kudu nindakake operasi maca lan nulis.
Panggunaan
Konfigurasi EKM sampeyan didhaptar ing tingkat organisasi liwat titik pungkasan anyar https://api.openai.com/v1/organization/external_keys.
Sawise ndhaptar konfigurasi EKM, sampeyan bakal nampa external_key_id kanthi format extkey_xxxx.
Konfigurasi EKM diaktifake ing tingkat proyek kanthi nglebokake external_key_id ing isi panjaluk menyang titik pungkasan Gawe Proyek sing wis ana, https://api.openai.com/v1/organization/projects.
Watesan
Sampeyan kudu nyoba EKM dhisik ing proyek anyar liwat API Manajemen.
Disaranake nggawe proyek anyar kanggo beban kerja EKM sampeyan. Gatekake praktik paling apik ing ngisor iki sadurunge ngetrapake EKM ing proyek produksi sampeyan sing wis ana.
Coba dhisik kabeh fitur API sing sampeyan gunakake ing produksi ing proyek API EKM kanggo uji coba.
Trapake EKM kanthi bertahap, aja langsung ing kabeh proyek API produksi bebarengan.
Endpoints level organisasi
Daftarake kunci eksternal ing organisasi sampeyan
AWS
Tuladha panjaluk:
type: string - mesthi “aws”
name: string - Jeneng sing gampang dingerteni kanggo konfigurasi sampeyan
role_arn: string - ARN peran sing bakal digunakake OpenAI ing cloud sampeyan
kms_arn: string - ARN Sistem Manajemen Kunci kanggo kunci utama sing sampeyan atur
external_id: string - ID Organisasi utawa ID proyek API sampeyan
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>"
}'Tuladha tanggapan:
{
"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
Tuladha panjaluk:
type: string - mesthi “gcp”,
name: string - Jeneng sing gampang dingerteni kanggo konfigurasi sampeyan
workload_identity_project_number: string - Nomer proyek GCP awujud angka ing ngendi sampeyan ndhaptar identitas beban kerja OpenAI
workload_identity_pool_id: string - Pool sing ngemot panyedhiya Workload Identity sing sampeyan dhaptar kanggo OpenAI
workload_identity_provider_id: string - Panyedhiya Workload Identity sing sampeyan dhaptar kanggo OpenAI
audience: string - Audiens sing kudu dilebokake OpenAI ing token nalika nggunakake peran liwat GCP STS sampeyan
kms_project_id: string - Jeneng proyek GCP sing dadi panggonan KMS sampeyan
kms_key_ring_name: string - Dering kunci Sistem Manajemen Kunci sing ngemot kunci utama sing sampeyan atur
kms_key_name: string - Jeneng kunci utama Sistem Manajemen Kunci
kms_key_location: string - Wilayah panggonan kunci utama Sistem Manajemen Kunci sampeyan
Yen KMS sampeyan ana ing proyek GCP sing beda karo proyek panggonan sampeyan ndhaptar Workload Identity OpenAI, priksa manawa paling ora KMS wis diaktifake ing proyek sing ngemot Workload Identity OpenAI kanthi mbukak 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"
}'Tuladha tanggapan:
{
"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
Tuladha panjaluk:
type: string - mesthi “azure”,
name: string - Jeneng sing gampang dingerteni kanggo konfigurasi sampeyan
tenant_id: string - UUID tenant Azure sampeyan
vault_uri: string - URI vault Azure sing ngemot kunci utama sing sampeyan atur
key_name: string - Jeneng kunci utama Azure Key Vault sing sampeyan atur.
Jeneng iki kudu nganggo format <org-xxx>--<any_name>
ing kene org-xxx yaiku ID Organisasi OpenAI sampeyan sing bisa ditemokake ing 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"
}'Tuladha tanggapan:
{
"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
Siapake kunci AES-256 sing aktif lan wenehana akses marang OpenAI. Kunci kasebut kudu duwe tag wangun bebas openai_organization_id sing disetel menyang ID Organisasi OpenAI sampeyan. Kanggo langkah-langkah persiyapan, deleng: Ngatur OCI Vault kanggo Manajemen Kunci Perusahaan.
Tuladha panjaluk:
type: string - mesthi "oci"
purpose: string - "ekm"; nilai gawan yen ora diisi
name: string - Jeneng sing gampang dingerteni kanggo konfigurasi sampeyan
region: string - Wilayah OCI panggonan vault lan kunci sampeyan
vault_ocid: string - OCID lengkap saka vault sampeyan
key_ocid: string - OCID lengkap saka kunci AES-256 sampeyan
Aja ngirim key_version_ocid kanggo 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>"
}'Tuladha tanggapan:
{
"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 ngasilake HTTP 200 yen kasil. Simpen id sing ditampa lan gunakake minangka external_key_id nalika nggawe proyek. Operasi sing wis ana kanggo ndeleng dhaptar, njupuk, validasi, lan mbusak uga bisa digunakake kanggo registrasi OCI.
Kanggo pamulihan PSP, gunakake registrasi RSA-3072 kapisah kanthi purpose: "psp_decryption" lan key_version_ocid sing persis cocog. Setel psp_decryption_key_id menyang ID registrasi OpenAI-ne. OpenAI mung mbutuhake akses maca menyang metadata lan kunci publik kanggo kunci RSA kasebut. Kanggo persiyapan lengkap, deleng: Nyiyapake kunci asimetris — OCI Vault.
Busak kunci eksternal sing kadhaptar ing organisasi sampeyan
Cathetan: Registrasi ora bisa dibusak nalika isih digunakake dening proyek utawa papan kerja sing aktif. Kanggo EKM, arsipake dhisik proyek API sing gegandhengan; registrasi EKM sing digandhengake karo papan kerja tetep dilindhungi. Kanggo pamulihan PSP, ganti utawa kosongake psp_decryption_key_id ing saben proyek aktif sing ngrujuk registrasi kasebut sadurunge mbusak registrasine. Mbusak registrasi OpenAI ora mbusak kunci cloud.
Tuladha panjaluk
curl -X DELETE \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys/extkey_xxxx"Tuladha 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>"
}Jupuk kunci eksternal sing kadhaptar ing organisasi sampeyan
Tanpa saringan purpose, dhaptar kasebut nyakup registrasi EKM lan pamulihan PSP. Gunakake ?purpose=ekm utawa ?purpose=psp_decryption kanggo nyaring miturut tujuwane.
Tuladha panjaluk
curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys"Tuladha 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
Gunakake validasi kanggo mriksa manawa OpenAI isih bisa ngakses kunci cloud sampeyan.
Kanggo EKM, OpenAI mriksa manawa bisa nindakake enkripsi lan dekripsi nganggo kunci kasebut. Kanggo cara kerjane pencabutan lan panyimpenan cache, deleng: pandhuan siklus urip kunci.
Kanggo pamulihan PSP, OpenAI njupuk kunci publik saka versi sing kadhaptar lan mbandhingake karo snapshot sing disimpen. Validasi sing kasil ora mesthekake manawa identitas pamulihan sampeyan bisa nindakake dekripsi. Validasi sing gagal ora mbusak utawa ngganti snapshot kunci publik sing disimpen.
Njupuk registrasi nganggo GET ngasilake konfigurasi sing disimpen lan ora mriksa maneh akses menyang kunci cloud sampeyan.
Tuladha panjaluk
curl -X POST -H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys/extkey_xxx/validate"Tuladha tanggapan
{
"status": "success"
}Utawa, ana error sing ditampilake saka panyedhiya cloud.
Endpoints level proyek
Gawe proyek anyar nganggo ID kunci eksternal
Iki padha karo titik pungkasan Gawe Proyek sing wis ana, nanging ana tambahan parameter external_key_id ing panjaluk lan respons.
Tuladha panjaluk
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"
}'Tuladha respons
{
"object": "organization.project",
"id": "proj_xxxxx",
"name": "Some Project",
"external_key_id": "extkey_xxxx",
"created_at": 1740012721,
"archived_at": null,
"status": "active"
}Anyari proyek sing wis ana nganggo ID kunci eksternal
Iki padha karo titik pungkasan Nganyari Proyek sing wis ana, kanthi tambahan parameter external_key_id ing panjaluk lan tanggapan.
Disaranake nggawe proyek API anyar kanggo beban kerja EKM sampeyan. Gatekake praktik paling apik ing ngisor iki sadurunge ngetrapake EKM ing proyek produksi sampeyan sing wis ana.
Coba dhisik kabeh fitur API sing sampeyan gunakake ing produksi ing proyek API EKM kanggo uji coba.
Trapake EKM kanthi bertahap, aja langsung ing kabeh proyek API produksi bebarengan.
Tuladha panjaluk
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"
}'Deleng dhaptar kabeh proyek ing organisasi sampeyan
Iki padha karo titik pungkasan sing wis ana, nanging ana tambahan external_key_id ing respons API.
Tuladha panjaluk
curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/projects"Tuladha 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
}