Özet
Erişim
EKM uç noktalarına Management API içinde bir Yönetici API Anahtarı ile erişilebilir. https://platform.openai.com/settings/organization/admin-keys (normal bir API anahtarı kullanmayın). Yönetici API anahtarları kuruluş sahipleri için 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 yazma işlemlerini gerçekleştirmesi gerekiyorsa ihtiyacı vardır.Şu anda kuruluşunuz için bu uç noktaları özellik bayrağıyla etkinleştirmemiz gerekiyor. Mevcut Projeleri Listele uç noktasından external_key_id döndürüldüğünü görüyorsanız özellik bayrağına sahip olduğunuzu anlarsınız: https://api.openai.com/v1/organization/projects
Kullanım
EKM yapılandırmanız, yeni bir uç nokta 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öner
EKM yapılandırmaları, mevcut Proje Oluştur https://api.openai.com/v1/organization/projects uç noktasının gövdesine bir external_key_id geçirilerek proje düzeyinde etkinleştirilir
Kısıtlamalar
Önce Management API üzerinden EKM’yi yeni bir projede test etmelisiniz.
EKM iş yükleriniz için yeni projeler oluşturmanızı öneririz. Ancak mevcut bir projede EKM istiyorsanız sizi özellik bayrağına ekleyebiliriz. EKM’yi mevcut üretim projelerinize sunmadan önce lütfen aşağıdaki en iyi uygulamalara dikkat edin.
Önce test EKM API projenizde üretimde kullandığınız tüm API özelliklerini test edin
EKM’yi tüm üretim API projelerine aynı anda doldurmak yerine kademeli bir dağıtım uygulayın
Kuruluş düzeyindeki uç noktalar
Kuruluşunuza bir harici anahtar kaydedin
AWS
Örnek İstek
type: string - her zaman “aws”
name: string - Yapılandırmanız için kolay anlaşılır bir ad
role_arn: string - OpenAI’ın 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 Yapılandırması",
"role_arn": "arn:aws:iam::<12_DIGIT_ACCOUNT_NUMBER>:role/<ROLE>",
"kms_arn": "arn:aws:kms:<REGION>:<ACCOUNT_NUMBER>:key/<UUID>",
"external_id": <kuruluş kimliğiniz veya proje kimliğiniz>
}'Örnek Yanıt
{
"id": "extkey_xxxx",
"object": "organization.external_key",
"created_at": 1746175499,
"api_project_ids": [],
"type": "aws",
"name": "AWS EKM Yapılandırması",
"role_arn": "arn:aws:iam::<ACCOUNT_NUMBER>:role/<ROLE>",
"kms_arn": "arn:aws:kms:<REGION>:<ACCOUNT_NUMBER>:key/<UUID>",
"external_id": <kuruluş kimliğiniz veya proje kimliğiniz>
} GCP
Örnek İstek
type: string - her zaman "gcp",
name: string - Yapılandırmanız için kolay anlaşılır bir ad
workload_identity_project_number: string - OpenAI’ın 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’ın token içinde geçirmesi gereken audience
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’ın Workload Identity’sini kaydettiğiniz projeden farklı bir GCP projesinde bulunuyorsa https://console.developers.google.com/apis/api/cloudkms.googleapis.com/overview adresine giderek en azından OpenAI’ın Workload Identity’sini içeren projede KMS’nin etkin olduğundan emin olun
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 Yapılandırması",
"workload_identity_project_number": "123456789012",
"workload_identity_pool_id": "openai-azure",
"workload_identity_provider_id": "openai-ekm-service-role",
"audience": <kuruluş kimliğiniz veya proje kimliğiniz>,
"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 Yapılandırması",
"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": <kuruluş kimliğiniz veya proje kimliğiniz>,
"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 kolay anlaşılır bir ad
tenant_id: string - Azure kiracı UUID’niz
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ı.
Şu biçimde olmalıdır: <org-xxx>--<any_name>
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 Yapılandırması",
"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 Yapılandırması",
"tenant_id": "<UUID>",
"vault_uri": "https://<VAULT_NAME>.vault.azure.net/",
"key_name": "org-xxx--some-key"
}Kuruluşunuza kayıtlı bir harici anahtarı silin
Not: Bir harici anahtarı yalnızca etkin projelerle ilişkili değilse silebilirsiniz. Etkin bir projeyle ilişkiliyse önce o projeyi arşivlemeniz gerekir.
Ö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 Yapılandırması",
"role_arn": "arn:aws:iam::<ACCOUNT_NUMBER>:role/<ROLE>"
}Kuruluşunuza 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 Yapılandırması",
"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 uç noktayı birkaç şeyi kontrol etmek için kullanabilirsiniz
Değişiklikler yaptıktan sonra harici bulut yapılandırmanızın OpenAI ile geçerliliğini koruyup korumadığını kontrol edebilirsiniz (bir başarı yanıtı görürsünüz)
Anahtar iptalinizin doğru yapıldığını, OpenAI tarafından işlendiğini ve 1 saatlik önbellek TTL’leri sona erdikten sonra etkili olacağını kontrol edebilirsiniz (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 kaynaklanan bir hata görüntülenebilir.
Proje düzeyindeki uç noktalar
Harici anahtar kimliğiyle yeni bir proje oluşturun
Bu, istek ve yanıtta external_key_id parametresinin eklenmesi dışında mevcut Proje Oluştur uç noktasıyla aynı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": "Bir Proje",
"external_key_id": "extkey_xxxx"
}'Örnek Yanıt
{
"object": "project",
"id": "proj_xxxxx",
"title": "Bir Proje",
"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ı] Harici anahtar kimliğiyle mevcut bir projeyi güncelleyin
Bu, istek ve yanıtta external_key_id parametresinin eklenmesi dışında mevcut Proje Güncelle uç noktasıyla aynıdır.
EKM iş yükleriniz için yeni API projeleri oluşturmanızı öneririz. Mevcut tüm API projelerinizde EKM istiyorsanız hesap yöneticinizle görüşün, sizi özellik bayrağına ekleyelim. EKM’yi mevcut üretim projelerinize sunmadan önce lütfen aşağıdaki en iyi uygulamalara dikkat edin.
Önce test EKM API projenizde üretimde kullandığınız tüm API özelliklerini test edin
EKM’yi tüm üretim API projelerine aynı anda doldurmak yerine kademeli bir dağıtım 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 uç noktayla aynıdır ancak API yanıtına external_key_id eklenmiştir
Ö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": "Proje Adı",
"external_key_id": "extkey_xxxx",
"created_at": 1717798982,
"archived_at": null,
"status": "active"
}
],
"first_id": "proj_xxxx",
"last_id": "proj_xxxx",
"has_more": true
}