Samantekt
Aðgangur
Endapunktar EKM eru aðgengilegir í stjórnunar-API með API-lykli stjórnanda. https://platform.openai.com/settings/organization/admin-keys (ekki nota venjulegan API-lykil). Eigendur fyrirtækis hafa aðgang að API-lyklum stjórnanda.
Notaðu
api.external_keys.writetil að búa til eða eyða ytri lyklum ogapi.external_keys.readtil að birta lista yfir ytri lykla, sækja þá eða sannreyna. Einn lykill þarf aðeins bæði heimildasviðin ef hann á að framkvæma bæði les- og skrifaðgerðir.
Notkun
EKM-uppsetningin þín er skráð fyrir fyrirtækið með nýjum endapunkti: https://api.openai.com/v1/organization/external_keys.
Þegar þú skráir EKM-uppsetninguna færðu external_key_id á forminu extkey_xxxx.
EKM-uppsetningar eru virkjaðar fyrir hvert verkefni með því að senda external_key_id í meginmáli beiðni til núverandi endapunkts sem býr til verkefni: https://api.openai.com/v1/organization/projects.
Takmarkanir
Þú verður fyrst að prófa EKM í nýju verkefni í gegnum stjórnunar-API.
Við mælum með að stofna ný verkefni fyrir vinnslu sem notar EKM. Kynntu þér eftirfarandi ráðleggingar áður en þú innleiðir EKM í verkefnum sem þegar eru í rekstri.
Prófaðu fyrst alla API-eiginleika sem þú notar í rekstri í API-prófunarverkefninu þínu með EKM.
Innleiddu EKM í áföngum í stað þess að virkja það í öllum API-verkefnum í rekstri í einu.
endpoints á fyrirtækisstigi
Skrá ytri lykil hjá fyrirtækinu þínu
AWS
Dæmi um beiðni:
type: strengur – alltaf „aws“
name: strengur – Lýsandi heiti á uppsetningunni þinni
role_arn: strengur – ARN-auðkenni hlutverksins sem OpenAI tekur að sér í skýjaumhverfinu þínu
kms_arn: strengur – ARN-auðkenni aðallykilsins sem þú stýrir í lyklastjórnunarkerfinu
external_id: strengur – Auðkenni fyrirtækis þíns eða API-verkefnis
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>"
}'Dæmi um svar:
{
"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
Dæmi um beiðni:
type: strengur – alltaf „gcp“,
name: strengur – Lýsandi heiti á uppsetningunni þinni
workload_identity_project_number: strengur – Númer GCP-verkefnisins þar sem þú skráðir vinnsluauðkenni OpenAI
workload_identity_pool_id: strengur – Safnið sem inniheldur Workload Identity-veituna sem þú skráðir fyrir OpenAI
workload_identity_provider_id: strengur – Workload Identity-veitan sem þú skráðir fyrir OpenAI
audience: strengur – Viðtakandinn sem OpenAI á að tilgreina í aðgangstákninu þegar við tökum að okkur hlutverk í gegnum GCP STS hjá þér
kms_project_id: strengur – Heiti GCP-verkefnisins þar sem KMS-kerfið þitt er
kms_key_ring_name: strengur – Lyklakippan í lyklastjórnunarkerfinu sem inniheldur aðallykilinn sem þú stýrir
kms_key_name: strengur – Heiti aðallykilsins í lyklastjórnunarkerfinu
kms_key_location: strengur – Svæðið þar sem aðallykillinn þinn í lyklastjórnunarkerfinu er staðsettur
Ef KMS-kerfið þitt er í öðru GCP-verkefni en því þar sem þú skráðir Workload Identity fyrir OpenAI skaltu ganga úr skugga um að KMS sé að minnsta kosti virkt í verkefninu sem inniheldur Workload Identity fyrir OpenAI. Farðu á https://console.developers.google.com/apis/api/cloudkms.googleapis.com/overview til að athuga það.
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"
}'Dæmi um svar:
{
"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
Dæmi um beiðni:
type: strengur – alltaf „azure“,
name: strengur – Lýsandi heiti á uppsetningunni þinni
tenant_id: strengur – UUID-auðkenni Azure-leigjandans þíns
vault_uri: strengur – URI-auðkenni Azure-lyklageymslunnar sem inniheldur aðallykilinn sem þú stýrir
key_name: strengur – Heiti aðallykilsins sem þú stýrir í Azure Key Vault.
Það verður að vera á forminu <org-xxx>--<any_name>
þar sem org-xxx er auðkenni fyrirtækis þíns hjá OpenAI, sem þú finnur á https://platform.openai.com/settings/organization/general
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"
}'Dæmi um svar:
{
"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
Settu upp virkan AES-256-lykil og veittu OpenAI aðgang. Lykillinn verður að hafa frjálst merki, openai_organization_id, með auðkenni fyrirtækisins þíns hjá OpenAI sem gildi. Sjá uppsetningarleiðbeiningar í: Uppsetning OCI Vault fyrir lyklastjórnun fyrirtækja.
Dæmi um beiðni:
type: strengur – alltaf "oci"
purpose: strengur – "ekm"; sjálfgefið gildi ef færibreytunni er sleppt
name: strengur – Auðskiljanlegt heiti á stillingunum þínum
region: strengur – OCI-svæðið þar sem lyklageymslan og lykillinn þinn eru
vault_ocid: strengur – Fullt OCID-auðkenni lyklageymslunnar þinnar
key_ocid: strengur – Fullt OCID-auðkenni AES-256-lykilsins þíns
Ekki senda key_version_ocid fyrir 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>"
}'Dæmi um svar:
{
"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-ið skilar HTTP 200 þegar aðgerðin tekst. Vistaðu id-gildið sem er skilað og notaðu það sem external_key_id þegar þú stofnar verkefni. Fyrirliggjandi aðgerðir til að birta lista, sækja, sannreyna og eyða eiga einnig við um OCI-skráningar.
Fyrir PSP-endurheimt skaltu nota sérstaka RSA-3072-skráningu með purpose: "psp_decryption" og nákvæmu key_version_ocid-gildi. Stilltu psp_decryption_key_id á skráningarauðkenni hennar hjá OpenAI. OpenAI þarf aðeins lesaðgang að lýsigögnum og dreifilyklum fyrir þennan RSA-lykil. Ítarlegar uppsetningarleiðbeiningar má finna í: Setja upp ósamhverfa lykla — OCI Vault.
Eyða ytri lykli sem er skráður á fyrirtækið þitt
Athugið: Ekki er hægt að eyða skráningunni á meðan virkt verkefni eða vinnusvæði notar hana. Fyrir EKM skaltu fyrst setja tengd API-verkefni í safn; EKM-skráning sem tengist vinnusvæði er áfram varin gegn eyðingu. Fyrir PSP-endurheimt skaltu breyta eða hreinsa psp_decryption_key_id í öllum virkum verkefnum sem vísa í skráninguna áður en henni er eytt. Þótt skráningu hjá OpenAI sé eytt er skýjalyklinum ekki eytt.
Dæmi um beiðni
curl -X DELETE \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys/extkey_xxxx"Dæmi um svar
{
"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>"
}Sækja ytri lykla sem eru skráðir á fyrirtækið þitt
Án síu eftir tilgangi inniheldur listinn bæði EKM-skráningar og skráningar fyrir PSP-endurheimt. Notaðu ?purpose=ekm eða ?purpose=psp_decryption til að sía eftir tilgangi.
Dæmi um beiðni
curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys"Dæmi um svar
{
"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"
}Sannreyna ytri lykil
Notaðu sannprófun til að athuga hvort OpenAI hafi enn aðgang að skýjalyklinum þínum.
Fyrir EKM athugar OpenAI hvort hægt sé að dulrita og afkóða með lyklinum. Upplýsingar um afturköllun og skyndiminnisnotkun má finna í leiðbeiningum um lífsferil lykla.
Fyrir PSP-endurheimt sækir OpenAI dreifilykil skráðu útgáfunnar og ber hann saman við vistaða afritið. Heppnuð sannprófun staðfestir ekki að auðkennið sem þú notar við endurheimt geti afkóðað. Misheppnuð sannprófun fjarlægir ekki vistaða afritið af dreifilyklinum né kemur öðru í stað þess.
Þegar skráning er sótt með GET er vistuðum stillingum skilað án þess að aðgangur að skýjalyklinum þínum sé athugaður aftur.
Dæmi um beiðni
curl -X POST -H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys/extkey_xxx/validate"Dæmi um svar
{
"status": "success"
}Eða villa sem kemur frá skýjaþjónustuveitunni.
endpoints á verkefnisstigi
Búa til nýtt verkefni með auðkenni ytri lykils
Þetta er sami endapunktur og áður til að búa til verkefni, en færibreytunni external_key_id hefur verið bætt við beiðnina og svarið.
Dæmi um beiðni
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"
}'Dæmi um svar
{
"object": "organization.project",
"id": "proj_xxxxx",
"name": "Some Project",
"external_key_id": "extkey_xxxx",
"created_at": 1740012721,
"archived_at": null,
"status": "active"
}Uppfæra fyrirliggjandi verkefni með auðkenni ytri lykils
Þetta er sami endapunktur og sá sem er þegar notaður til að uppfæra verkefni, en færibreytunni external_key_id hefur verið bætt við beiðnina og svarið.
Við mælum með að stofna ný API-verkefni fyrir vinnslu sem notar EKM. Kynntu þér eftirfarandi ráðleggingar áður en þú innleiðir EKM í verkefnum sem þegar eru í rekstri.
Prófaðu fyrst alla API-eiginleika sem þú notar í rekstri í API-prófunarverkefninu þínu með EKM.
Innleiddu EKM í áföngum í stað þess að virkja það í öllum API-verkefnum í rekstri í einu.
Dæmi um beiðni
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"
}'Birta lista yfir öll verkefni fyrirtækisins þíns
Þetta er sami endapunktur og áður, en external_key_id hefur verið bætt við API-svarið.
Dæmi um beiðni
curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/projects"Dæmi um svar
{
"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
}