Samenvatting
Toegang
EKM-endpoints zijn toegankelijk in de Management API met een API-beheerderssleutel. https://platform.openai.com/settings/organization/admin-keys (gebruik geen gewone API-sleutel). API-beheerderssleutels zijn beschikbaar voor organisatie-eigenaren.
Gebruik
api.external_keys.writeom externe sleutels aan te maken of te verwijderen enapi.external_keys.readom externe sleutels weer te geven, op te halen of te valideren. Een sleutel heeft alleen beide scopes nodig als deze zowel lees- als schrijfbewerkingen moet uitvoeren.
Gebruik
Je EKM-configuratie wordt geregistreerd op het niveau van de organisatie via een nieuw endpoint: https://api.openai.com/v1/organization/external_keys.
Bij het registreren van je EKM-configuratie wordt een external_key_id geretourneerd in de vorm extkey_xxxx.
EKM-configuraties worden geactiveerd op het niveau van een project door een external_key_id mee te geven in de body van het verzoek aan het bestaande endpoint voor het aanmaken van een project: https://api.openai.com/v1/organization/projects.
Beperkingen
Je moet EKM eerst via de Management API testen op een nieuw project.
We raden aan nieuwe projecten aan te maken voor je EKM-workloads. Neem de volgende aanbevelingen door voordat je EKM uitrolt naar je bestaande productieprojecten.
Test alle API-functies die je in productie gebruikt eerst in je API-testproject met EKM.
Rol EKM geleidelijk uit in plaats van het in één keer voor alle API-productieprojecten in te stellen.
Endpoints op organisatieniveau
Een externe sleutel bij je organisatie registreren
AWS
Voorbeeldverzoek:
type: string - altijd "aws"
name: string - Een herkenbare naam voor je configuratie
role_arn: string - De ARN van de rol die OpenAI in je cloud zal aannemen
kms_arn: string - De ARN in het sleutelbeheersysteem voor de hoofdsleutel die je beheert
external_id: string - Je Organisatie-ID of 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>"
}'Voorbeeldrespons:
{
"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
Voorbeeldverzoek:
type: string - altijd "gcp",
name: string - Een herkenbare naam voor je configuratie
workload_identity_project_number: string - Het numerieke nummer van het GCP-project waarin je de Workload Identity van OpenAI hebt geregistreerd
workload_identity_pool_id: string - De pool met de Workload Identity-provider die je voor OpenAI hebt geregistreerd
workload_identity_provider_id: string - De Workload Identity-provider die je voor OpenAI hebt geregistreerd
audience: string - De audience die OpenAI in het token moet meegeven wanneer we via je GCP STS een rol aannemen
kms_project_id: string - De naam van het GCP-project waarin je KMS zich bevindt
kms_key_ring_name: string - De sleutelring in het sleutelbeheersysteem met de hoofdsleutel die je beheert
kms_key_name: string - De naam van de hoofdsleutel in het sleutelbeheersysteem
kms_key_location: string - De regio waarin de hoofdsleutel van je sleutelbeheersysteem zich bevindt
Als je KMS zich in een ander GCP-project bevindt dan het project waarin je de Workload Identity van OpenAI hebt geregistreerd, zorg er dan voor dat KMS in elk geval is ingeschakeld voor het project met de Workload Identity van OpenAI. Ga hiervoor naar 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"
}'Voorbeeldrespons:
{
"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
Voorbeeldverzoek:
type: string - altijd "azure",
name: string - Een herkenbare naam voor je configuratie
tenant_id: string - De UUID van je Azure-tenant
vault_uri: string - De URI van de Azure-kluis met de hoofdsleutel die je beheert
key_name: string - De naam van de hoofdsleutel in Azure Key Vault die je beheert.
Deze moet de vorm <org-xxx>--<any_name> hebben
waarbij org-xxx je Organisatie-ID bij OpenAI is, die je kunt vinden op 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"
}'Voorbeeldrespons:
{
"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
Stel een ingeschakelde AES-256-sleutel in en verleen OpenAI toegang. De sleutel moet een vrije tag openai_organization_id hebben met je Organisatie-ID bij OpenAI als waarde. Zie voor de configuratiestappen: OCI Vault configureren voor Enterprise Key Management.
Voorbeeldverzoek:
type: string - altijd "oci"
purpose: string - "ekm"; de standaardwaarde als deze parameter wordt weggelaten
name: string - Een herkenbare naam voor je configuratie
region: string - De OCI-regio waarin je kluis en sleutel zich bevinden
vault_ocid: string - De volledige OCID van je kluis
key_ocid: string - De volledige OCID van je AES-256-sleutel
Geef key_version_ocid niet mee voor 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>"
}'Voorbeeldrespons:
{
"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>"
}De API retourneert HTTP 200 als het verzoek slaagt. Sla de geretourneerde id op en gebruik deze als external_key_id wanneer je een project aanmaakt. De bestaande bewerkingen voor weergeven, ophalen, valideren en verwijderen zijn ook van toepassing op OCI-registraties.
Gebruik voor PSP-herstel een aparte RSA-3072-registratie met purpose: "psp_decryption" en een exacte key_version_ocid. Stel psp_decryption_key_id in op de bijbehorende OpenAI-registratie-ID. OpenAI heeft voor die RSA-sleutel alleen leestoegang nodig tot de metagegevens en openbare sleutels. Zie voor de volledige configuratie: Asymmetrische sleutels instellen — OCI Vault.
Een externe sleutel verwijderen die voor je organisatie is geregistreerd
Opmerking: Verwijderen wordt geblokkeerd zolang een actief project of een actieve werkruimte de registratie gebruikt. Archiveer voor EKM eerst de gekoppelde API-projecten; een EKM-registratie die aan een werkruimte is gekoppeld, blijft beschermd. Vervang of wis voor PSP-herstel psp_decryption_key_id in elk actief project dat naar de registratie verwijst voordat je de registratie verwijdert. Als je een OpenAI-registratie verwijdert, wordt de cloudsleutel niet verwijderd.
Voorbeeldverzoek
curl -X DELETE \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys/extkey_xxxx"Voorbeeldrespons
{
"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>"
}De externe sleutels ophalen die voor je organisatie zijn geregistreerd
Zonder filter op purpose bevat de lijst zowel EKM-registraties als registraties voor PSP-herstel. Gebruik ?purpose=ekm of ?purpose=psp_decryption om op doel te filteren.
Voorbeeldverzoek
curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys"Voorbeeldrespons
{
"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"
}Een externe sleutel valideren
Gebruik validatie om te controleren of OpenAI nog steeds toegang heeft tot je cloudsleutel.
Voor EKM controleert OpenAI of het met de sleutel kan versleutelen en ontsleutelen. Zie voor informatie over intrekking en caching: richtlijnen voor de levenscyclus van sleutels.
Voor PSP-herstel haalt OpenAI de openbare sleutel van de geregistreerde versie op en vergelijkt deze met de opgeslagen momentopname. Een geslaagde validatie bevestigt niet dat je herstelidentiteit kan ontsleutelen. Een mislukte validatie verwijdert of vervangt de opgeslagen momentopname van de openbare sleutel niet.
Als je een registratie ophaalt met GET, wordt de opgeslagen configuratie geretourneerd en wordt de toegang tot je cloudsleutel niet opnieuw gecontroleerd.
Voorbeeldverzoek
curl -X POST -H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys/extkey_xxx/validate"Voorbeeldrespons
{
"status": "success"
}Of een fout die door de cloudprovider is gemeld.
Endpoints op projectniveau
Een nieuw project aanmaken met een externe sleutel-ID
Dit is hetzelfde als het bestaande endpoint voor het aanmaken van een project, maar met de toevoeging van de parameter external_key_id in het verzoek en de respons.
Voorbeeldverzoek
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"
}'Voorbeeldrespons
{
"object": "organization.project",
"id": "proj_xxxxx",
"name": "Some Project",
"external_key_id": "extkey_xxxx",
"created_at": 1740012721,
"archived_at": null,
"status": "active"
}Een bestaand project bijwerken met een externe sleutel-ID
Dit is hetzelfde als het bestaande endpoint Update Project, met als toevoeging de parameter external_key_id in het verzoek en de respons.
We raden aan nieuwe API-projecten aan te maken voor je EKM-workloads. Neem de volgende aanbevelingen door voordat je EKM uitrolt naar je bestaande productieprojecten.
Test alle API-functies die je in productie gebruikt eerst in je API-testproject met EKM.
Rol EKM geleidelijk uit in plaats van het in één keer voor alle API-productieprojecten in te stellen.
Voorbeeldverzoek
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"
}'Alle projecten in je organisatie opsommen
Dit is hetzelfde als het bestaande endpoint, maar met de toevoeging van external_key_id in de API-respons.
Voorbeeldverzoek
curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/projects"Voorbeeldrespons
{
"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
}