OpenAI
Þessi síða var vélþýdd. Skoða upprunalegu ensku greinina.

EKM (ytri lyklar) í Management API

Lærðu að stjórna ytri lyklum fyrir EKM með stjórnunar-API.

Uppfært: 3 hours ago

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.write til að búa til eða eyða ytri lyklum og api.external_keys.read til 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

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.

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
}

Var þessi grein gagnleg?