Özet
Erişim
EKM uç noktalarına Yönetim API’si üzerinden 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ını kuruluş sahipleri kullanabilir.
Harici anahtar oluşturmak veya silmek için
api.external_keys.write, harici anahtarları listelemek veya doğrulamak içinapi.external_keys.readkapsamını kullanın. Bir anahtarın her iki kapsama da ihtiyacı olması için hem okuma hem de yazma işlemlerini gerçekleştirmesi gerekir.Şu anda kuruluşunuzun bu uç noktalara erişebilmesi için bir özellik bayrağını etkinleştirmemiz gerekiyor. Mevcut Projeleri Listele uç noktası https://api.openai.com/v1/organization/projects yanıtında external_key_id alanını görüyorsanız özellik bayrağı sizin için etkindir.
Kullanım
EKM yapılandırmanız, yeni https://api.openai.com/v1/organization/external_keys uç noktası aracılığıyla 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 Proje Oluştur uç noktasına (https://api.openai.com/v1/organization/projects) gönderilen isteğin gövdesinde bir external_key_id iletilerek proje düzeyinde etkinleştirilir.
Kısıtlamalar
Önce EKM’yi Yönetim API’si aracılığıyla yeni bir projede test etmelisiniz.
EKM iş yükleriniz için yeni projeler oluşturmanızı öneririz. Ancak mevcut bir projede EKM kullanmak istiyorsanız sizin için özellik bayrağını etkinleştirebiliriz. EKM’yi mevcut üretim projelerinizde devreye almadan önce aşağıdaki en iyi uygulamaları dikkate alın.
Üretim ortamında kullandığınız tüm API özelliklerini önce EKM test API projenizde test edin.
EKM’yi tüm üretim API projelerinde aynı anda etkinleştirmek yerine kademeli olarak devreye alın.
Kuruluş düzeyindeki endpoint'ler
Kuruluşunuzda bir harici anahtar kaydedin
AWS
Örnek istek:
type: string - her zaman “aws”
name: string - Yapılandırmanız için kolay anlaşılır bir ad
role_arn: string - OpenAI’ın bulut ortamınızda üstleneceği rolün ARN’si
kms_arn: string - Yönettiğiniz ana anahtarın Anahtar Yönetim Sistemi ARN’si
external_id: string - Kuruluş Kimliğiniz veya API projenizin kimliği
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 istek:
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 iş yükü kimliğini kaydettiğiniz GCP projesinin sayısal 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 - OpenAI’ın GCP STS hizmetiniz üzerinden bir rol üstlenirken belirteçte iletmesi 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 Anahtar Yönetim Sistemi anahtar halkası
kms_key_name: string - Anahtar Yönetim Sistemi ana anahtarının adı
kms_key_location: string - Anahtar Yönetim Sistemi ana anahtarınızın bulunduğu bölge
KMS’niz, OpenAI’ın Workload Identity kimliğini kaydettiğiniz GCP projesinden farklı bir projede bulunuyorsa https://console.developers.google.com/apis/api/cloudkms.googleapis.com/overview adresine giderek OpenAI’ın Workload Identity kimliğini içeren projede en azından 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 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 istek:
type: string - her zaman “azure”,
name: string - Yapılandırmanız için kolay anlaşılır 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ı.
<org-xxx>--<any_name> biçiminde 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şunuza kayıtlı bir harici anahtarı silin
Not: Bir harici anahtarı yalnızca etkin bir API projesi veya çalışma alanıyla ilişkili değilse silebilirsiniz. Etkin bir API projesiyle ilişkiliyse önce o projeyi arşivleyin. Bir çalışma alanıyla ilişkiliyse anahtar silinemez.
Örnek istek
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şunuza kayıtlı harici anahtarları alın
Örnek istek
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 uç noktayı aşağıdakileri kontrol etmek için kullanabilirsiniz:
Değişiklik yaptıktan sonra harici bulut yapılandırmanızın OpenAI ile kullanım için hâlâ geçerli olup olmadığını (başarılı bir yanıt görürsünüz).
Anahtar iptal işleminizin doğru yapılıp yapılmadığını, OpenAI tarafından işlenip işlenmediğini ve 1 saatlik önbellek TTL süreleri dolduktan sonra geçerli olup olmayacağını (bir hata yanıtı görürsünüz).
Örnek istek
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
Mevcut Proje Oluştur uç noktasıyla aynıdır; tek fark, istek ve yanıta external_key_id parametresinin eklenmesidir.
Örnek istek
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": "organization.project",
"id": "proj_xxxxx",
"name": "Some Project",
"external_key_id": "extkey_xxxx",
"created_at": 1740012721,
"archived_at": null,
"status": "active"
}[Kısıtlı] Mevcut bir projeyi harici anahtar kimliğiyle güncelleyin
Mevcut Projeyi Güncelle uç noktasıyla aynıdır; tek fark, istek ve yanıta external_key_id parametresinin eklenmesidir.
EKM iş yükleriniz için yeni API projeleri oluşturmanızı öneririz. Mevcut API projelerinizin tamamında EKM kullanmak istiyorsanız hesap yöneticinizle iletişime geçin; sizin için özellik bayrağını etkinleştirelim. EKM’yi mevcut üretim projelerinizde devreye almadan önce aşağıdaki en iyi uygulamaları dikkate alın.
Üretim ortamında kullandığınız tüm API özelliklerini önce EKM test API projenizde test edin.
EKM’yi tüm üretim API projelerinde aynı anda etkinleştirmek yerine kademeli olarak devreye alın.
Örnek istek
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
Mevcut uç noktayla aynıdır; tek fark, API yanıtına external_key_id alanının eklenmesidir.
Örnek istek
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
}