Özet
Erişim
EKM endpoint'lerine Management API içinde bir Admin API Key ile erişilebilir. https://platform.openai.com/settings/organization/admin-keys (normal bir API anahtarı kullanmayın). Admin API anahtarları kuruluş sahipleri tarafından kullanılabilir.
Harici anahtarlar oluşturmak veya silmek için
api.external_keys.write, harici anahtarları listelemek veya doğrulamak içinapi.external_keys.readkullanın. Tek bir anahtarın her iki kapsama da yalnızca hem okuma hem de yazma işlemleri yapması gerekiyorsa ihtiyacı vardır.Bu endpoint'leri kullanabilmeniz için şu anda kuruluşunuzu feature flag'e almamız gerekiyor. Mevcut List Projects endpoint'inden dönen yanıtta external_key_id görüyorsanız feature flag'e sahipsiniz: https://api.openai.com/v1/organization/projects
Kullanım
EKM yapılandırmanız, yeni bir endpoint olan https://api.openai.com/v1/organization/external_keys üzerinden kuruluş düzeyinde kaydedilir.
EKM yapılandırmanızı kaydettiğinizde extkey_xxxx biçiminde bir external_key_id döndürülür
EKM yapılandırmaları, mevcut Create Project https://api.openai.com/v1/organization/projects endpoint'inin gövdesinde external_key_id geçirilerek proje düzeyinde etkinleştirilir.
Kısıtlamalar
Önce Management API üzerinden yeni bir projede EKM'yi test etmelisiniz.
EKM iş yükleriniz için yeni projeler oluşturmanızı öneririz. Ancak mevcut bir projede EKM kullanmak istiyorsanız sizi feature flag'e ekleyebiliriz. EKM'yi mevcut üretim projelerinizde kullanıma almadan önce lütfen aşağıdaki en iyi uygulamalara dikkat edin.
Üretimde kullandığınız tüm API özelliklerini önce test EKM API projenizde test edin
EKM'yi tüm üretim API projelerine aynı anda eklemek yerine kademeli bir kullanıma alma uygulayın
Kuruluş düzeyindeki endpoint'ler
Kuruluşunuzda bir harici anahtar kaydedin
AWS
Örnek İstek
type: string - her zaman “aws”
name: string - yapılandırmanız için kullanıcı dostu bir ad
role_arn: string - OpenAI'nin bulutunuzda üstleneceği Role ARN
kms_arn: string - yönettiğiniz ana anahtar için Key Management System ARN'si
external_id: string - kuruluş kimliğiniz veya API proje kimliğiniz
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>
}'Örnek Yanıt
{
"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
Örnek İstek
type: string - her zaman "gcp",
name: string - yapılandırmanız için kullanıcı dostu bir ad
workload_identity_project_number: string - OpenAI'nin workload identity'sini kaydettiğiniz 12 haneli GCP proje numarası
workload_identity_pool_id: string - OpenAI için kaydettiğiniz Workload Identity sağlayıcısını içeren havuz
workload_identity_provider_id: string - OpenAI için kaydettiğiniz Workload Identity sağlayıcısı
audience: string - GCP STS'niz üzerinden rol üstlendiğimizde OpenAI'nin token içinde geçirmesi gereken hedef kitle
kms_project_id: string - KMS'nizin bulunduğu GCP projesinin adı
kms_key_ring_name: string - yönettiğiniz ana anahtarı içeren Key Management System anahtar halkası
kms_key_name: string - Key Management System ana anahtarının adı
kms_key_location: string - Key Management System ana anahtarınızın bulunduğu bölge
KMS'niz, OpenAI'nin Workload Identity'sini kaydettiğinizden farklı bir GCP projesindeyse OpenAI'nin Workload Identity'sini içeren projede en azından KMS'nin etkin olduğundan emin olmak için https://console.developers.google.com/apis/api/cloudkms.googleapis.com/overview adresine gidin
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"
}'Örnek Yanıt
{
"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
Örnek İstek
type: string - her zaman "azure",
name: string - yapılandırmanız için kullanıcı dostu bir ad
tenant_id: string - Azure kiracınızın UUID'si
vault_uri: string - yönettiğiniz ana anahtarı içeren Azure kasasının URI'si
key_name: string - yönettiğiniz Azure Key Vault ana anahtarının adı.
Biçimi <org-xxx>--<any_name> olmalıdır
burada org-xxx, https://platform.openai.com/settings/organization/general adresinde bulabileceğiniz OpenAI kuruluş kimliğinizdir
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"
}'Örnek Yanıt
{
"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"
}Kuruluşunuzda kayıtlı bir harici anahtarı silin
Not: Bir harici anahtarı yalnızca hiçbir aktif API projesiyle veya çalışma alanıyla ilişkili değilse silebilirsiniz. Aktif bir API projesiyle ilişkiliyse önce o projeyi arşivleyin. Bir çalışma alanıyla ilişkiliyse anahtar silinemez.
Örnek İstek
curl -X DELETE \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys/extkey_xxxx"Örnek Yanıt
{
"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>"
}Kuruluşunuzda kayıtlı harici anahtarları alın
Örnek İstek
curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys"Örnek Yanıt
{
"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"
}Bir harici anahtarı doğrulayın
Bu endpoint'i birkaç şeyi kontrol etmek için kullanabilirsiniz
Harici bulut yapılandırmanız, değişiklik yaptıktan sonra OpenAI ile geçerliliğini koruyor mu (başarılı bir yanıt görürsünüz)
Anahtar iptaliniz doğru yapıldı mı, OpenAI tarafından işleniyor mu ve 1 saatlik önbellek TTL'leri dolduktan sonra yürürlüğe girecek mi (bir hata yanıtı görürsünüz)
Örnek İstek
curl -X POST -H "Authorization: Bearer $TOKEN"
"https://api.openai.com/v1/organization/external_keys/extkey_xxx/validate"Örnek Yanıt
{
"status": "success"
}Veya bulut sağlayıcısından gelen bir hata gösterilir.
Proje düzeyindeki endpoint'ler
Harici anahtar kimliğiyle yeni bir proje oluşturun
Bu, mevcut Create Project endpoint'iyle aynıdır; tek fark istek ve yanıta external_key_id parametresinin eklenmiş olmasıdır.
Örnek İstek
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"
}'Örnek Yanıt
{
"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,
}[Kısıtlı] Mevcut bir projeyi harici anahtar kimliğiyle güncelleyin
Bu, mevcut Update Project endpoint'iyle aynıdır; tek fark istek ve yanıta external_key_id parametresinin eklenmiş olmasıdır.
EKM iş yükleriniz için yeni API projeleri oluşturmanızı öneririz. Mevcut tüm API projelerinizde EKM kullanmak istiyorsanız hesap yöneticinizden isteyin; sizi feature flag'e ekleyelim. EKM'yi mevcut üretim projelerinizde kullanıma almadan önce lütfen aşağıdaki en iyi uygulamalara dikkat edin.
Üretimde kullandığınız tüm API özelliklerini önce test EKM API projenizde test edin
EKM'yi tüm üretim API projelerine aynı anda eklemek yerine kademeli bir kullanıma alma uygulayın
Örnek İstek
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"
}'Kuruluşunuzdaki tüm projeleri listeleyin
Bu, mevcut endpoint ile aynıdır; tek fark API yanıtına external_key_id eklenmiş olmasıdır.
Örnek İstek
curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/projects"Örnek Yanıt
{
"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
}