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

EKM (Kunci Eksternal) ing Management API

Atur kunci eksternal kanggo EKM nganggo Management API

Pembaruan: 14 days ago

Ringkesan

Akses

  • Endpoints EKM bisa diakses ing Management API 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 nampilake dhaptar utawa validasi kunci eksternal. Siji kunci mung mbutuhake loro scope yen kudu nindakake operasi maca lan nulis.

  • Saiki kita kudu ngaktifake feature flag kanggo organisasi sampeyan supaya bisa nggunakake endpoints iki. Sampeyan ngerti yen feature flag wis aktif yen weruh external_key_id dibalekake saka endpoint List Projects sing wis ana: https://api.openai.com/v1/organization/projects

Panggunaan

Watesan

  • Sampeyan kudu ngetes EKM dhisik ing proyek anyar liwat Management API.

  • Disaranake sampeyan nggawe proyek anyar kanggo workload EKM sampeyan. Nanging, yen sampeyan pengin EKM ing proyek sing wis ana, kita bisa nambahake sampeyan menyang feature flag. Gatekna praktik paling apik ing ngisor iki sadurunge sampeyan ngetrapake EKM menyang proyek produksi sing wis ana.

    • Tes dhisik kabeh fitur API sing sampeyan gunakake ing produksi ing proyek API EKM test sampeyan

    • Terapake rollout bertahap, aja ngisi EKM ing kabeh proyek API produksi sekaligus

Endpoints level organisasi

Daftarake kunci eksternal ing organisasi sampeyan

AWS

Tuladha Panjaluk

  • type: string -  tansah “aws”

  • name: string -  Jeneng sing gampang dikenali kanggo konfigurasi sampeyan

  • role_arn: string - Role ARN sing bakal di-assume OpenAI ing cloud sampeyan

  • kms_arn: string - ARN Sistem Manajemen Kunci kanggo kunci master sing sampeyan kelola

  • 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 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

Tuladha Panjaluk

  • type: string - tansah  "gcp",

  • name: string - Jeneng sing gampang dikenali kanggo konfigurasi sampeyan

  • workload_identity_project_number: string - Nomer proyek GCP 12 digit ing ngendi sampeyan ndaftarake workload identity OpenAI

  • workload_identity_pool_id: string - Pool sing ngemot panyedhiya Workload Identity sing sampeyan daftarake kanggo OpenAI

  • workload_identity_provider_id: string - Panyedhiya Workload Identity sing sampeyan daftarake kanggo OpenAI

  • audience: string - Audience sing kudu diterusake OpenAI ing token nalika kita assume role liwat GCP STS sampeyan

  • kms_project_id: string - Jeneng proyek GCP panggonan KMS sampeyan ana

  • kms_key_ring_name: string - Key ring Sistem Manajemen Kunci sing ngemot kunci master sing sampeyan kelola

  • kms_key_name: string - Jeneng kunci master Sistem Manajemen Kunci

  • kms_key_location: string - Region panggonan kunci master Sistem Manajemen Kunci sampeyan ana

Yen KMS sampeyan ana ing proyek GCP sing beda saka proyek panggonan sampeyan ndaftarake Workload Identity OpenAI, priksa manawa proyek sing ngemot Workload Identity OpenAI paling ora wis ngaktifake KMS 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 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

Tuladha Panjaluk

  • type: string - tansah  "azure",

  • name: string - Jeneng sing gampang dikenali kanggo konfigurasi sampeyan

  • tenant_id: string - UUID tenant Azure sampeyan

  • vault_uri: string - URI vault Azure sing ngemot kunci master sing sampeyan kelola

  • key_name: string - Jeneng kunci master Azure Key Vault sing sampeyan 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"
}'

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

Busak kunci eksternal sing didaftarake ing organisasi sampeyan

Cathetan: Sampeyan mung bisa mbusak kunci eksternal yen ora digandhengake karo proyek API aktif utawa papan kerja apa wae. Yen digandhengake karo proyek API aktif, arsipna proyek kuwi dhisik. Yen digandhengake karo papan kerja, kunci kasebut ora bisa dibusak.

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

Entuk kunci eksternal sing didaftarake ing organisasi sampeyan

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

Sampeyan bisa nggunakake endpoint iki kanggo mriksa sawetara perkara

  • Konfigurasi cloud eksternal sampeyan tetep valid karo OpenAI sawise sampeyan nggawe owah-owahan (sampeyan bakal weruh respons sukses)

  • Pencabutan kunci sampeyan wis rampung kanthi bener, lagi diproses dening OpenAI, lan bakal efektif sawise TTL cache 1 jam kadaluwarsa (sampeyan bakal weruh respons error)

Tuladha Panjaluk

curl -X POST -H "Authorization: Bearer $TOKEN"
"https://api.openai.com/v1/organization/external_keys/extkey_xxx/validate"

Tuladha Respons

{
 "status": "success"
}

Utawa, ana error sing ditampilake saka panyedhiya cloud.

Endpoints level proyek

Gawe proyek anyar nganggo ID kunci eksternal

Iki padha karo endpoint Create Project sing wis ana, nanging ditambah 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": "project",
  "id": "proj_xxxxx",
  "title": "Some Project",
  "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] Nganyari proyek sing wis ana nganggo ID kunci eksternal

Iki padha karo endpoint Update Project sing wis ana, nanging ditambah parameter external_key_id ing panjaluk lan respons.


Disaranake sampeyan nggawe proyek API anyar kanggo workload EKM sampeyan. Yen sampeyan pengin EKM ing kabeh proyek API sing wis ana, takona direktur akun sampeyan lan kita bakal nambahake sampeyan menyang feature flag. Gatekna praktik paling apik ing ngisor iki sadurunge sampeyan ngetrapake EKM menyang proyek produksi sing wis ana.

  • Tes dhisik kabeh fitur API sing sampeyan gunakake ing produksi ing proyek API EKM test sampeyan

  • Terapake rollout bertahap, aja ngisi EKM ing kabeh proyek API produksi sekaligus

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

Tampilake dhaptar kabeh proyek ing organisasi sampeyan

Iki padha karo endpoint sing wis ana, nanging ditambah 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?