Oversigt
Adgang
EKM-endepunkter er tilgængelige i administrations-API'et via en administrator-API-nøgle. https://platform.openai.com/settings/organization/admin-keys (brug ikke en almindelig API-nøgle). Administrator-API-nøgler er tilgængelige for organisationsejere.
Brug
api.external_keys.writetil at oprette eller slette eksterne nøgler ogapi.external_keys.readtil at vise en liste over, hente eller validere eksterne nøgler. En nøgle behøver kun begge rettighedsområder, hvis den skal udføre både læse- og skriveoperationer.
Brug
Din EKM-konfiguration registreres for hele organisationen via et nyt endepunkt: https://api.openai.com/v1/organization/external_keys.
Når du registrerer din EKM-konfiguration, returneres et external_key_id i formatet extkey_xxxx.
EKM-konfigurationer aktiveres for det enkelte projekt ved at sende et external_key_id i anmodningens indhold til det eksisterende endepunkt til at oprette projekter: https://api.openai.com/v1/organization/projects.
Begrænsninger
Du skal først teste EKM på et nyt projekt via administrations-API'et.
Vi anbefaler at oprette nye projekter til dine EKM-arbejdsbelastninger. Følg disse anbefalinger, før du udruller EKM til dine eksisterende produktionsprojekter.
Test først alle API-funktioner, som du bruger i produktion, i dit API-testprojekt med EKM.
Udrul EKM gradvist i stedet for at aktivere det på alle API-projekter i produktion på én gang.
End points på organisationsniveau
Registrer en ekstern nøgle i din organisation
AWS
Eksempel på anmodning:
type: streng – altid »aws«
name: streng – Et letgenkendeligt navn til din konfiguration
role_arn: streng – ARN for den rolle, som OpenAI påtager sig i dit cloudmiljø
kms_arn: streng – ARN i nøgleadministrationssystemet for den hovednøgle, du administrerer
external_id: streng – Dit 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>"
}'Eksempel 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
Eksempel på anmodning:
type: streng – altid »gcp«,
name: streng – Et letgenkendeligt navn til din konfiguration
workload_identity_project_number: streng – Det numeriske projektnummer for det GCP-projekt, hvor du registrerede OpenAI's workloadidentitet
workload_identity_pool_id: streng – Den pulje, der indeholder den Workload Identity-udbyder, du registrerede for OpenAI
workload_identity_provider_id: streng – Den Workload Identity-udbyder, du registrerede for OpenAI
audience: streng – Den målgruppe, OpenAI skal angive i tokenet, når vi påtager os en rolle via din GCP STS
kms_project_id: streng – Navnet på det GCP-projekt, hvor dit KMS er placeret
kms_key_ring_name: streng – Den nøglering i nøgleadministrationssystemet, der indeholder den hovednøgle, du administrerer
kms_key_name: streng – Navnet på hovednøglen i nøgleadministrationssystemet
kms_key_location: streng – Den region, hvor hovednøglen i dit nøgleadministrationssystem er placeret
Hvis dit KMS er placeret i et andet GCP-projekt end det, hvor du registrerede OpenAI's Workload Identity, skal du sikre dig, at KMS som minimum er aktiveret i projektet med OpenAI's Workload Identity. Det gør du ved at gå til 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"
}'Eksempel 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
Eksempel på anmodning:
type: streng – altid »azure«,
name: streng – Et letgenkendeligt navn til din konfiguration
tenant_id: streng – UUID'et for din Azure-lejer
vault_uri: streng – URI'en for den Azure-nøgleboks, der indeholder den hovednøgle, du administrerer
key_name: streng – Navnet på den hovednøgle i Azure Key Vault, du administrerer.
Det skal have formatet <org-xxx>--<any_name>
hvor org-xxx er dit OpenAI-organisations-id, som du kan finde 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"
}'Eksempel 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
Konfigurer en aktiveret AES-256-nøgle, og giv OpenAI adgang. Nøglen skal have et frit defineret openai_organization_id-tag, der er indstillet til dit OpenAI-organisations-id. Se opsætningsvejledningen her: Konfiguration af OCI Vault til Enterprise Key Management.
Eksempel på anmodning:
type: streng – altid "oci"
purpose: streng – "ekm"; standardværdien, hvis feltet udelades
name: streng – Et beskrivende navn til din konfiguration
region: streng – Den OCI-region, hvor din vault og nøgle er placeret
vault_ocid: streng – Det fulde OCID for din vault
key_ocid: streng – Det fulde OCID for din AES-256-nøgle
Angiv ikke key_version_ocid for 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>"
}'Eksempel 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 returnerer HTTP 200, når anmodningen lykkes. Gem det returnerede id, og brug det som external_key_id, når du opretter et projekt. De eksisterende operationer til at vise lister, hente, validere og slette gælder også for OCI-registreringer.
Til PSP-gendannelse skal du bruge en separat RSA-3072-registrering med purpose: "psp_decryption" og et præcist key_version_ocid. Indstil psp_decryption_key_id til registreringens id hos OpenAI. OpenAI behøver kun læseadgang til metadata og offentlige nøgler for den pågældende RSA-nøgle. Se den komplette opsætningsvejledning her: Opsæt asymmetriske nøgler – OCI Vault.
Slet en ekstern nøgle, der er registreret i din organisation
Bemærk: Sletning er blokeret, så længe et aktivt projekt eller arbejdsområde bruger registreringen. For EKM skal du først arkivere de tilknyttede API-projekter. En EKM-registrering, der er knyttet til et arbejdsområde, er fortsat beskyttet. For PSP-gendannelse skal du erstatte eller rydde psp_decryption_key_id på alle aktive projekter, der henviser til registreringen, før du sletter den. Når du sletter en OpenAI-registrering, slettes nøglen i skyen ikke.
Eksempel på anmodning
curl -X DELETE \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys/extkey_xxxx"Eksempel 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>"
}Hent de eksterne nøgler, der er registreret i din organisation
Uden et filter for formål indeholder listen både EKM-registreringer og registreringer til PSP-gendannelse. Brug ?purpose=ekm eller ?purpose=psp_decryption til at filtrere efter formål.
Eksempel på anmodning
curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys"Eksempel 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"
}Valider en ekstern nøgle
Brug validering til at kontrollere, at OpenAI stadig har adgang til din nøgle i skyen.
For EKM kontrollerer OpenAI, at nøglen kan bruges til kryptering og dekryptering. Læs om tilbagekaldelse og caching i vejledningen om nøglers livscyklus.
For PSP-gendannelse henter OpenAI den registrerede versions offentlige nøgle og sammenligner den med det gemte øjebliksbillede. En vellykket validering bekræfter ikke, at din gendannelsesidentitet kan dekryptere. En mislykket validering fjerner eller erstatter ikke det gemte øjebliksbillede af den offentlige nøgle.
Når du henter en registrering med GET, returneres den gemte konfiguration, uden at adgangen til din nøgle i skyen kontrolleres igen.
Eksempel på anmodning
curl -X POST -H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys/extkey_xxx/validate"Eksempel på svar
{
"status": "success"
}Eller en fejl, der blev returneret fra cloududbyderen.
End points på projektniveau
Opret et nyt projekt med et eksternt nøgle-id
Dette er det samme som det eksisterende endepunkt til at oprette projekter, men med parameteren external_key_id tilføjet i anmodningen og svaret.
Eksempel på anmodning
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"
}'Eksempel på svar
{
"object": "organization.project",
"id": "proj_xxxxx",
"name": "Some Project",
"external_key_id": "extkey_xxxx",
"created_at": 1740012721,
"archived_at": null,
"status": "active"
}Opdater et eksisterende projekt med et eksternt nøgle-id
Dette svarer til det eksisterende endepunkt til projektopdatering, men med parameteren external_key_id tilføjet i anmodningen og svaret.
Vi anbefaler at oprette nye API-projekter til dine EKM-arbejdsbelastninger. Følg disse anbefalinger, før du udruller EKM til dine eksisterende produktionsprojekter.
Test først alle API-funktioner, som du bruger i produktion, i dit API-testprojekt med EKM.
Udrul EKM gradvist i stedet for at aktivere det på alle API-projekter i produktion på én gang.
Eksempel på anmodning
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"
}'Vis alle projekter i din organisation
Dette er det samme som det eksisterende endepunkt, men med external_key_id tilføjet i API-svaret.
Eksempel på anmodning
curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/projects"Eksempel 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
}