Sammanfattning
Åtkomst
EKM-slutpunkter är tillgängliga i hanterings-API:et via en API-nyckel för administratörer. https://platform.openai.com/settings/organization/admin-keys (använd inte en vanlig API-nyckel). API-nycklar för administratörer är tillgängliga för organisationsägare.
Använd
api.external_keys.writeför att skapa eller ta bort externa nycklar ochapi.external_keys.readför att lista, hämta eller validera externa nycklar. En enskild nyckel behöver båda behörighetsomfången endast om den ska utföra både läs- och skrivåtgärder.
Användning
Din EKM-konfiguration registreras på organisationsnivå via en ny slutpunkt: https://api.openai.com/v1/organization/external_keys.
När du registrerar din EKM-konfiguration returneras ett external_key_id i formatet extkey_xxxx.
EKM-konfigurationer aktiveras på projektnivå genom att du skickar med ett external_key_id i begärans kropp till den befintliga slutpunkten för att skapa projekt: https://api.openai.com/v1/organization/projects.
Begränsningar
Du måste först testa EKM i ett nytt projekt via hanterings-API:et.
Vi rekommenderar att du skapar nya projekt för dina EKM-arbetsbelastningar. Tänk på följande rekommendationer innan du inför EKM i dina befintliga produktionsprojekt.
Testa först alla API-funktioner som du använder i produktion i ditt API-testprojekt för EKM.
Inför EKM gradvis i stället för att aktivera det i alla API-projekt i produktion samtidigt.
Endpoints på organisationsnivå
Registrera en extern nyckel för din organisation
AWS
Exempel på begäran:
type: sträng – alltid ”aws”
name: sträng – Ett lättläst namn på din konfiguration
role_arn: sträng – ARN för den roll som OpenAI ska anta i din molnmiljö
kms_arn: sträng – ARN i nyckelhanteringssystemet för den huvudnyckel du hanterar
external_id: sträng – Ditt organisations-ID eller API-projekt-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>"
}'Exempel på 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
Exempel på begäran:
type: sträng – alltid ”gcp”,
name: sträng – Ett lättläst namn på din konfiguration
workload_identity_project_number: sträng – Det numeriska projektnumret för GCP-projektet där du registrerade OpenAI:s arbetsbelastningsidentitet
workload_identity_pool_id: sträng – Poolen som innehåller den Workload Identity-provider som du registrerade för OpenAI
workload_identity_provider_id: sträng – Den Workload Identity-provider som du registrerade för OpenAI
audience: sträng – Den målgrupp som OpenAI ska ange i token när vi antar en roll via din GCP STS
kms_project_id: sträng – Namnet på GCP-projektet där ditt KMS finns
kms_key_ring_name: sträng – Nyckelringen i nyckelhanteringssystemet som innehåller den huvudnyckel du hanterar
kms_key_name: sträng – Namnet på huvudnyckeln i nyckelhanteringssystemet
kms_key_location: sträng – Regionen där huvudnyckeln i ditt nyckelhanteringssystem finns
Om ditt KMS finns i ett annat GCP-projekt än det där du registrerade OpenAI:s Workload Identity ska du säkerställa att KMS åtminstone är aktiverat i projektet som innehåller OpenAI:s Workload Identity. Det gör du genom att gå till 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"
}'Exempel på 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
Exempel på begäran:
type: sträng – alltid ”azure”,
name: sträng – Ett lättläst namn på din konfiguration
tenant_id: sträng – UUID för din Azure-klientorganisation
vault_uri: sträng – URI för det Azure-valv som innehåller den huvudnyckel du hanterar
key_name: sträng – Namnet på den huvudnyckel i Azure Key Vault som du hanterar.
Det måste ha formatet <org-xxx>--<any_name>
där org-xxx är ditt organisations-ID hos OpenAI, som du hittar på 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"
}'Exempel på 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
Konfigurera en aktiverad AES-256-nyckel och ge OpenAI åtkomst. Nyckeln måste ha en fritexttagg, openai_organization_id, med ditt organisations-ID hos OpenAI som värde. Konfigurationsanvisningar finns i: Konfigurera OCI Vault för Enterprise Key Management.
Exempel på begäran:
type: sträng – alltid "oci"
purpose: sträng – "ekm"; standardvärdet om parametern utelämnas
name: sträng – ett lättläst namn på din konfiguration
region: sträng – OCI-regionen där ditt valv och din nyckel finns
vault_ocid: sträng – ditt valvs fullständiga OCID
key_ocid: sträng – din AES-256-nyckels fullständiga OCID
Skicka inte med key_version_ocid för 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>"
}'Exempel på 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:et returnerar HTTP 200 när åtgärden lyckas. Spara det returnerade id-värdet och använd det som external_key_id när du skapar ett projekt. De befintliga åtgärderna för att lista, hämta, validera och ta bort gäller även för OCI-registreringar.
För PSP-återställning använder du en separat RSA-3072-registrering med purpose: "psp_decryption" och ett exakt key_version_ocid. Ange registreringens ID hos OpenAI som värde för psp_decryption_key_id. OpenAI behöver endast läsåtkomst till metadata och publika nycklar för den RSA-nyckeln. Fullständiga konfigurationsanvisningar finns i: Konfigurera asymmetriska nycklar – OCI Vault.
Ta bort en extern nyckel som är registrerad för din organisation
Obs! Borttagning blockeras så länge ett aktivt projekt eller en aktiv arbetsyta använder registreringen. För EKM ska du först arkivera de kopplade API-projekten. En EKM-registrering som är kopplad till en arbetsyta förblir skyddad. För PSP-återställning ska du ersätta eller rensa psp_decryption_key_id i varje aktivt projekt som refererar till registreringen innan du tar bort den. Om du tar bort en OpenAI-registrering tas inte molnnyckeln bort.
Exempel på begäran
curl -X DELETE \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys/extkey_xxxx"Exempel på 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>"
}Hämta de externa nycklar som är registrerade för din organisation
Utan filtrering efter syfte innehåller listan registreringar för både EKM och PSP-återställning. Använd ?purpose=ekm eller ?purpose=psp_decryption för att filtrera efter syfte.
Exempel på begäran
curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys"Exempel på 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"
}Validera en extern nyckel
Använd validering för att kontrollera att OpenAI fortfarande har åtkomst till din molnnyckel.
För EKM kontrollerar OpenAI att det går att kryptera och dekryptera med nyckeln. Information om hur återkallande och cachelagring fungerar finns i: vägledning om nyckelns livscykel.
För PSP-återställning hämtar OpenAI den registrerade versionens publika nyckel och jämför den med den lagrade ögonblicksbilden. En lyckad validering bekräftar inte att din återställningsidentitet kan dekryptera. En misslyckad validering tar inte bort eller ersätter den lagrade ögonblicksbilden av den publika nyckeln.
När du hämtar en registrering med GET returneras den lagrade konfigurationen utan att åtkomsten till din molnnyckel kontrolleras på nytt.
Exempel på begäran
curl -X POST -H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys/extkey_xxx/validate"Exempel på svar
{
"status": "success"
}Eller ett fel som kommer från molnleverantören.
Endpoints på projektnivå
Skapa ett nytt projekt med ett externt nyckel-ID
Detta är samma som den befintliga slutpunkten för att skapa projekt, men med parametern external_key_id tillagd i begäran och svaret.
Exempel på begäran
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"
}'Exempel på svar
{
"object": "organization.project",
"id": "proj_xxxxx",
"name": "Some Project",
"external_key_id": "extkey_xxxx",
"created_at": 1740012721,
"archived_at": null,
"status": "active"
}Uppdatera ett befintligt projekt med ett externt nyckel-ID
Detta motsvarar den befintliga slutpunkten för att uppdatera projekt, med tillägget av parametern external_key_id i begäran och svaret.
Vi rekommenderar att du skapar nya API-projekt för dina EKM-arbetsbelastningar. Tänk på följande rekommendationer innan du inför EKM i dina befintliga produktionsprojekt.
Testa först alla API-funktioner som du använder i produktion i ditt API-testprojekt för EKM.
Inför EKM gradvis i stället för att aktivera det i alla API-projekt i produktion samtidigt.
Exempel på begäran
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"
}'Lista alla projekt i din organisation
Detta är samma som den befintliga slutpunkten, men med tillägget external_key_id i API-svaret.
Exempel på begäran
curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/projects"Exempel på 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
}