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: 31 minutes ago

Buod

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 maglista, kumuha, o mag-validate ng mga external key. Kailangan lang ng isang key ang parehong scope kung gagamitin ito para sa parehong read at write na operasyon.

Paggamit

Mga paghihigpit

  • Dapat mo munang subukan ang EKM sa isang bagong proyekto gamit ang Management API.

  • Inirerekomenda naming gumawa ng mga bagong proyekto para sa iyong mga EKM workload. Isaalang-alang 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>"
}'

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

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

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

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

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

OCI

Mag-set up ng naka-enable na AES-256 key at bigyan ng access ang OpenAI. Dapat may free-form na openai_organization_id tag ang key na nakatakda sa iyong OpenAI Organization ID. Para sa mga hakbang sa pag-set up, tingnan ang: Pag-configure ng OCI Vault para sa Enterprise Key Management.

Halimbawang request:

  • type: string - palaging "oci"

  • purpose: string - "ekm"; ang default kapag hindi tinukoy

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

  • region: string - Ang rehiyon ng OCI kung saan naroon ang iyong vault at key

  • vault_ocid: string - Ang buong OCID ng iyong vault

  • key_ocid: string - Ang buong OCID ng iyong AES-256 key

Huwag ipasa ang key_version_ocid para sa 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>"
}'

Halimbawang response:

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

Nagbabalik ang API ng HTTP 200 kapag matagumpay ang operasyon. I-save ang ibinalik na id at gamitin ito bilang external_key_id kapag gumagawa ng proyekto. Nalalapat din sa mga pagpaparehistro sa OCI ang mga kasalukuyang operasyon para sa paglilista, pagkuha, pag-validate, at pag-delete.

Para sa PSP recovery, gumamit ng hiwalay na pagpaparehistro ng RSA-3072 na may purpose: "psp_decryption" at eksaktong key_version_ocid. Itakda ang psp_decryption_key_id sa ID ng pagpaparehistro nito sa OpenAI. Read access lang sa metadata at mga public key para sa RSA key na iyon ang kailangan ng OpenAI. Para sa kumpletong pag-set up, tingnan ang: Mag-set up ng mga asymmetric key — OCI Vault.

Mag-delete ng external key na nakarehistro sa iyong organisasyon

Tandaan: Hindi puwedeng mag-delete habang ginagamit ng isang aktibong proyekto o workspace ang pagpaparehistro. Para sa EKM, i-archive muna ang mga kaugnay na API project; mananatiling protektado ang pagpaparehistro ng EKM na nauugnay sa workspace. Para sa PSP recovery, palitan o alisin ang halaga ng psp_decryption_key_id sa bawat aktibong proyektong tumutukoy sa pagpaparehistro bago ito i-delete. Hindi nade-delete ang cloud key kapag nag-delete ng pagpaparehistro sa OpenAI.

Halimbawang 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 iyong organisasyon

Kung walang filter na purpose, kasama sa listahan ang mga pagpaparehistro para sa EKM at PSP recovery. Gamitin ang ?purpose=ekm o ?purpose=psp_decryption para mag-filter ayon sa layunin.

Halimbawang 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

Gamitin ang validation para tiyaking maa-access pa rin ng OpenAI ang iyong cloud key.

  • Para sa EKM, sinusuri ng OpenAI kung kaya nitong mag-encrypt at mag-decrypt gamit ang key. Para sa kung paano gumagana ang pagbawi ng access at pag-cache, tingnan ang: gabay sa lifecycle ng key.

  • Para sa PSP recovery, kinukuha ng OpenAI ang public key ng nakarehistrong bersyon at inihahambing ito sa nakaimbak na snapshot. Hindi kinukumpirma ng matagumpay na validation na kayang mag-decrypt ng iyong recovery identity. Hindi inaalis o pinapalitan ng nabigong validation ang nakaimbak na snapshot ng public key.

Kapag kumukuha ng pagpaparehistro gamit ang GET, ibinabalik nito ang nakaimbak na configuration at hindi nito muling sinusuri ang access sa iyong cloud key.

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

Mag-update ng kasalukuyang proyekto 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. Isaalang-alang 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.

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