Sammanfattning
Åtkomst
EKM-endpoints är åtkomliga i Management API via en Admin API-nyckel. https://platform.openai.com/settings/organization/admin-keys (använd inte en vanlig API-nyckel). Admin API-nycklar ä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 eller validera externa nycklar. En enskild nyckel behöver båda omfattningarna endast om den måste utföra både läs- och skrivåtgärder.För närvarande behöver vi ge din organisation åtkomst till dessa endpoints via en funktionsflagga. Du vet att du har funktionsflaggan om du ser external_key_id returneras från den befintliga List Projects-endpointen: https://api.openai.com/v1/organization/projects
Användning
Din EKM-konfiguration registreras på organisationsnivå via en ny endpoint 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 skicka med ett external_key_id i brödtexten till den befintliga Create Project-endpointen https://api.openai.com/v1/organization/projects
Begränsningar
Du måste först testa EKM i ett nytt projekt via Management API.
Vi rekommenderar att du skapar nya projekt för dina EKM-arbetsbelastningar. Men om du vill använda EKM i ett befintligt projekt kan vi lägga till dig i funktionsflaggan. Observera följande bästa praxis innan du rullar ut EKM till dina befintliga produktionsprojekt.
Testa först alla API-funktioner som du använder i produktion i ditt EKM-testprojekt för API
Rulla ut gradvis i stället för att aktivera EKM i alla produktions-API-projekt på en gång
Endpoints på organisationsnivå
Registrera en extern nyckel för din organisation
AWS
Exempelbegäran
type: string – alltid ”aws”
name: string – ett lättläst namn för din konfiguration
role_arn: string – den Role ARN som OpenAI ska anta i ditt moln
kms_arn: string – Key Management System-ARN för huvudnyckeln du hanterar
external_id: string – 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>
}'Exempelsvar
{
"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
Exempelbegäran
type: string – alltid ”gcp”,
name: string – ett lättläst namn för din konfiguration
workload_identity_project_number: string – det 12-siffriga GCP-projektnumret där du registrerade OpenAI:s Workload Identity
workload_identity_pool_id: string – poolen som innehåller den Workload Identity-provider som du registrerade för OpenAI
workload_identity_provider_id: string – den Workload Identity-provider som du registrerade för OpenAI
audience: string – den målgrupp som OpenAI ska skicka i token när vi antar en roll via din GCP STS
kms_project_id: string – namnet på GCP-projektet där din KMS finns
kms_key_ring_name: string – Key Management System-nyckelringen som innehåller huvudnyckeln du hanterar
kms_key_name: string – namnet på Key Management System-huvudnyckeln
kms_key_location: string – regionen där din Key Management System-huvudnyckel finns
Om din KMS finns i ett annat GCP-projekt än det där du registrerade OpenAI:s Workload Identity, se till att projektet som innehåller OpenAI:s Workload Identity åtminstone har KMS aktiverat 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"
}'Exempelsvar
{
"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
Exempelbegäran
type: string – alltid ”azure”,
name: string – ett lättläst namn för din konfiguration
tenant_id: string – din UUID för Azure-klientorganisationen
vault_uri: string – URI:n för det Azure-valv som innehåller huvudnyckeln du hanterar
key_name: string – namnet på Azure Key Vault-huvudnyckeln som du hanterar.
Det måste ha formatet <org-xxx>--<any_name>
där org-xxx är ditt OpenAI-organisations-ID, 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"
}'Exempelsvar
{
"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"
}Ta bort en extern nyckel som registrerats för din organisation
Obs! Du kan bara ta bort en extern nyckel om den inte är kopplad till några aktiva API-projekt eller någon Arbetsyta. Om den är kopplad till ett aktivt API-projekt arkiverar du projektet först. Om den är kopplad till en Arbetsyta går nyckeln inte att ta bort.
Exempelbegäran
curl -X DELETE \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys/extkey_xxxx"Exempelsvar
{
"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
Exempelbegäran
curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys"Exempelsvar
{
"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
Du kan använda denna endpoint för att kontrollera flera saker
Din externa molnkonfiguration förblir giltig hos OpenAI efter att du har gjort ändringar (du får ett svar om att åtgärden lyckades)
Din nyckelåterkallelse är korrekt utförd, behandlas av OpenAI och träder i kraft när cachelagringens TTL på 1 timme har löpt ut (du får ett felsvar)
Exempelbegäran
curl -X POST -H "Authorization: Bearer $TOKEN"
"https://api.openai.com/v1/organization/external_keys/extkey_xxx/validate"Exempelsvar
{
"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 Create Project-endpointen, med tillägget parametern external_key_id i begäran och svaret.
Exempelbegä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"
}'Exempelsvar
{
"object": "project",
"id": "proj_xxxxx",
"title": "Some Project",
"external_key_id": "extkey_xxxxx",
"created": 1740012721,
"organization_id": "org-xxxxx",
"is_initial": false,
"geography": null,
"scale_tier_enabled": false,
"disable_user_api_keys": false,
"zdr_type": null,
}[Begränsad] Uppdatera ett befintligt projekt med ett externt nyckel-ID
Detta är samma som den befintliga Update Project-endpointen, med tillägget parametern external_key_id i begäran och svaret.
Vi rekommenderar att du skapar nya API-projekt för dina EKM-arbetsbelastningar. Om du vill använda EKM i alla dina befintliga API-projekt kontaktar du din account director, så lägger vi till dig i funktionsflaggan. Observera följande bästa praxis innan du rullar ut EKM till dina befintliga produktionsprojekt.
Testa först alla API-funktioner som du använder i produktion i ditt EKM-testprojekt för API
Rulla ut gradvis i stället för att aktivera EKM i alla produktions-API-projekt på en gång
Exempelbegä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 endpointen, men med tillägget external_key_id i API-svaret
Exempelbegäran
curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/projects"Exempelsvar
{
"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
}