OpenAI
Kaca iki diterjemahake nganggo mesin. Deleng artikel asli basa Inggris.

EKM (Kunci Eksternal) ing Management API

Sinau carane ngatur kunci eksternal kanggo EKM nganggo API Manajemen.

Pembaruan: 40 minutes ago

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.write kanggo nggawe utawa mbusak kunci eksternal, lan api.external_keys.read kanggo ndeleng dhaptar, njupuk, utawa validasi kunci eksternal. Siji kunci mung mbutuhake loro cakupan ijin kasebut yen kudu nindakake operasi maca lan nulis.

Panggunaan

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.

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
}

Apa artikel iki migunani kanggo sampeyan?