OpenAI
Ang page na ito ay isinalin ng AI. Tingnan ang orihinal na artikulo sa English.

EKM (External Keys) sa Management API

Pamahalaan ang mga external key para sa EKM gamit ang Management API

Na-update: 14 days ago

Buod

Pag-access

  • Naa-access ang mga EKM endpoint sa Management API gamit ang Admin API Key. https://platform.openai.com/settings/organization/admin-keys (huwag gumamit ng karaniwang API key). Available ang mga Admin API key sa mga may-ari ng organisasyon.

  • Gamitin ang api.external_keys.write para gumawa o mag-delete ng mga external key, at ang api.external_keys.read para ilista o i-validate ang mga external key. Kailangan lang ng iisang key ang parehong scope kung dapat nitong magsagawa ng parehong read at write operations.

  • Sa kasalukuyan, kailangan naming i-enable ang feature flag para sa iyong organisasyon sa mga endpoint na ito. Malalaman mong mayroon kang feature flag kung makikita mo ang external_key_id na ibinalik mula sa kasalukuyang List Projects endpoint: https://api.openai.com/v1/organization/projects

Paggamit

Mga Restriksiyon

  • Kailangan mo munang subukan ang EKM sa isang bagong project sa pamamagitan ng Management API.

  • Inirerekomenda naming gumawa ng mga bagong project para sa iyong mga EKM workload. Gayunpaman, kung gusto mo ng EKM sa isang kasalukuyang project, maaari ka naming idagdag sa feature flag. Pakitandaan ang sumusunod na best practices bago mo i-roll out ang EKM sa iyong kasalukuyang production projects.

    • Subukan muna sa iyong test EKM API project ang lahat ng API feature na ginagamit mo sa production

    • Gumamit ng dahan-dahang rollout sa halip na lagyan ng EKM ang lahat ng production API project nang sabay-sabay

Mga endpoint sa antas ng organisasyon

Magrehistro ng external key sa iyong organisasyon

AWS

Halimbawang Request

  • type: string -  palaging “aws”

  • name: string -  Isang madaling tandaan na pangalan para sa iyong config

  • role_arn: string - Ang Role ARN na gagamitin ng OpenAI sa iyong cloud

  • kms_arn: string - Ang Key Management System ARN para sa master key na pinamamahalaan mo

  • external_id: string - ID ng iyong organisasyon o API project

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

Halimbawang Response

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

Halimbawang Request

  • type: string - palaging  "gcp",

  • name: string - Isang madaling tandaan na pangalan para sa iyong config

  • workload_identity_project_number: string - Ang 12-digit na GCP project number kung saan mo nirehistro ang workload identity ng OpenAI

  • workload_identity_pool_id: string - Ang pool na naglalaman ng Workload Identity provider na nirehistro mo para sa OpenAI

  • workload_identity_provider_id: string - Ang Workload Identity provider na nirehistro mo para sa OpenAI

  • audience: string - Ang audience na dapat ipasa ng OpenAI sa token kapag nag-assume kami ng role sa pamamagitan ng iyong GCP STS

  • kms_project_id: string - Ang pangalan ng GCP project kung saan naroon ang iyong KMS

  • kms_key_ring_name: string - Ang Key Management System key ring na naglalaman ng master key na pinamamahalaan mo

  • kms_key_name: string - Ang pangalan ng Key Management System master key

  • kms_key_location: string - Ang rehiyon kung saan matatagpuan ang iyong Key Management System master key

Kung ang iyong KMS ay nasa ibang GCP project kaysa sa project kung saan mo nirehistro ang Workload Identity ng OpenAI, tiyaking ang project na naglalaman ng Workload Identity ng OpenAI ay may naka-enable man lang na KMS sa pamamagitan ng pagpunta sa 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"
}'

Halimbawang Response

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

Halimbawang Request

  • type: string - palaging  "azure",

  • name: string - Isang madaling tandaan na pangalan para sa iyong config

  • tenant_id: string - Ang UUID ng iyong Azure tenant

  • vault_uri: string - Ang URI ng Azure vault na naglalaman ng master key na pinamamahalaan mo

  • key_name: string - Ang pangalan ng Azure Key Vault master key na pinamamahalaan mo.

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

Halimbawang Response

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

Mag-delete ng external key na nakarehistro sa iyong organisasyon

Tandaan: Maaari ka lang mag-delete ng external key kung hindi ito nauugnay sa anumang aktibong API project o workspace. Kung nauugnay ito sa isang aktibong API project, i-archive muna ang project na iyon. Kung nauugnay ito sa isang workspace, hindi maaaring i-delete ang key.

Halimbawang Request

curl -X DELETE \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys/extkey_xxxx"

Halimbawang Response

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

Kunin ang mga external key na nakarehistro sa iyong organisasyon

Halimbawang Request

curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys"

Halimbawang Response

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

I-validate ang external key

Magagamit mo ang endpoint na ito para suriin ang ilang bagay

  • Nananatiling valid sa OpenAI ang iyong external cloud configuration pagkatapos mong gumawa ng mga pagbabago (makakakita ka ng success response)

  • Nagawa nang tama ang pag-revoke ng iyong key, pinoproseso ito ng OpenAI, at magkakabisa ito pagkatapos mag-expire ang 1 oras na cache TTLs (makakakita ka ng error response)

Halimbawang Request

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

Halimbawang Response

{
 "status": "success"
}

O kaya, may lumitaw na error mula sa cloud provider.

Mga endpoint sa antas ng proyekto

Gumawa ng bagong project gamit ang external key ID

Kapareho ito ng kasalukuyang Create Project endpoint, na may dagdag na parameter na external_key_id sa request at response.

Halimbawang Request

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

Halimbawang Response

{
  "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] I-update ang kasalukuyang project gamit ang external key ID

Kapareho ito ng kasalukuyang Update Project endpoint, na may dagdag na parameter na external_key_id sa request at response.


Inirerekomenda naming gumawa ng mga bagong API project para sa iyong mga EKM workload. Kung gusto mo ng EKM sa lahat ng kasalukuyan mong API project, itanong sa iyong account director at idaragdag ka namin sa feature flag. Pakitandaan ang sumusunod na best practices bago mo i-roll out ang EKM sa iyong kasalukuyang production projects.

  • Subukan muna sa iyong test EKM API project ang lahat ng API feature na ginagamit mo sa production

  • Gumamit ng dahan-dahang rollout sa halip na lagyan ng EKM ang lahat ng production API project nang sabay-sabay

Halimbawang Request

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

Ilista ang lahat ng project sa iyong organisasyon

Kapareho ito ng kasalukuyang endpoint ngunit may dagdag na external_key_id sa API response

Halimbawang Request

curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/projects"

Halimbawang Response

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

Nakatulong ba ang artikulong ito?