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

EKM (External Keys) sa Management API

Alamin kung paano pamahalaan ang mga external key para sa EKM gamit ang Management API.

Na-update: 2 days ago

Buod

Pag-access

  • Maa-access ang mga EKM endpoint sa Management API gamit ang isang 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 isang key ang parehong scope kung gagamitin ito para sa parehong read at write na operasyon.

  • Sa kasalukuyan, kailangan naming i-enable ang feature flag para ma-access ng inyong organisasyon ang mga endpoint na ito. Malalaman mong naka-enable ang feature flag kung makikita mo ang external_key_id sa ibinabalik ng kasalukuyang List Projects endpoint: https://api.openai.com/v1/organization/projects.

Paggamit

Mga paghihigpit

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

  • Inirerekomenda naming gumawa ng mga bagong project para sa iyong mga EKM workload. Gayunpaman, kung gusto mong gumamit ng EKM sa isang kasalukuyang project, maaari naming i-enable ang feature flag para sa iyo. Tandaan ang mga sumusunod na inirerekomendang gawain bago mo ipatupad ang EKM sa iyong mga kasalukuyang production project.

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

    • Unti-unting ipatupad ang EKM sa halip na sabay-sabay itong ilapat sa lahat ng production API project.

Mga endpoint sa antas ng organisasyon

Magrehistro ng external key sa iyong organisasyon

AWS

Halimbawa ng request:

  • type: string - laging “aws”

  • name: string - Isang madaling makilalang pangalan para sa iyong configuration

  • role_arn: string - Ang ARN ng role na gagampanan ng OpenAI sa iyong cloud

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

  • external_id: string - Ang iyong Organization ID o API project ID

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

Halimbawa ng 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

Halimbawa ng request:

  • type: string - laging “gcp”,

  • name: string - Isang madaling makilalang pangalan para sa iyong configuration

  • workload_identity_project_number: string - Ang numerong nakatalaga sa GCP project kung saan mo inirehistro ang workload identity ng OpenAI

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

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

  • audience: string - Ang audience na dapat ipasa ng OpenAI sa token kapag gumaganap 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 ring ng Key Management System na naglalaman ng master key na pinapamahalaan mo

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

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

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

Halimbawa ng 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

Halimbawa ng request:

  • type: string - laging “azure”,

  • name: string - Isang madaling makilalang pangalan para sa iyong configuration

  • tenant_id: string - Ang UUID ng iyong Azure tenant

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

  • key_name: string - Ang pangalan ng master key ng Azure Key Vault na pinapamahalaan 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"
}'

Halimbawa ng 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 inyong organisasyon

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

Halimbawa ng request

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

Halimbawa ng 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 inyong organisasyon

Halimbawa ng request

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

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

Mag-validate ng external key

Maaari mong gamitin ang endpoint na ito para suriin ang ilang bagay:

  • Valid pa rin ang iyong external cloud configuration sa OpenAI matapos kang gumawa ng mga pagbabago (makakakita ka ng success response).

  • Tama ang pagkaka-revoke ng iyong key, pinoproseso ito ng OpenAI, at magkakabisa ito kapag nag-expire na ang 1-oras na mga cache TTL (makakakita ka ng error response).

Halimbawa ng request

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

Halimbawa ng response

{
  "status": "success"
}

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

Mga endpoint sa antas ng proyekto

Gumawa ng bagong project na may external key ID

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

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

Halimbawa ng response

{
  "object": "organization.project",
  "id": "proj_xxxxx",
  "name": "Some Project",
  "external_key_id": "extkey_xxxx",
  "created_at": 1740012721,
  "archived_at": null,
  "status": "active"
}

[Limitado ang access] I-update ang isang kasalukuyang project gamit ang external key ID

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

Inirerekomenda naming gumawa ng mga bagong API project para sa iyong mga EKM workload. Kung gusto mong gumamit ng EKM sa lahat ng kasalukuyan mong API project, makipag-ugnayan sa iyong account director at ie-enable namin ang feature flag para sa iyo. Tandaan ang mga sumusunod na inirerekomendang gawain bago mo ipatupad ang EKM sa iyong mga kasalukuyang production project.

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

  • Unti-unting ipatupad ang EKM sa halip na sabay-sabay itong ilapat sa lahat ng production API project.

Halimbawa ng 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 inyong organisasyon

Katulad ito ng kasalukuyang endpoint, pero may dagdag na external_key_id sa API response.

Halimbawa ng request

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

Halimbawa ng 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?