OpenAI
Bu sayfanın çevirisi otomatik olarak yapılmıştır. Orijinal İngilizce makaleyi görüntüleyin.

Management API'de EKM (Harici Anahtarlar)

Yönetim API’sini kullanarak EKM için harici anahtarları nasıl yöneteceğinizi öğrenin.

Güncellenme zamanı: 1 hour ago

Özet

Erişim

  • EKM uç noktalarına Yönetim API'sinde 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 tarafından kullanılabilir.

  • Harici anahtarları oluşturmak veya silmek için api.external_keys.write; listelemek, getirmek veya doğrulamak için api.external_keys.read kullanın. Bir anahtarın her iki yetki kapsamına da ihtiyacı olması için hem okuma hem de yazma işlemlerini gerçekleştirmesi gerekir.

Kullanım

Kısıtlamalar

  • Önce Yönetim API'si aracılığıyla EKM'yi yeni bir projede test etmelisiniz.

  • EKM iş yükleriniz için yeni projeler oluşturmanızı öneririz. Mevcut üretim projelerinizde EKM'yi kullanıma almadan önce aşağıdaki en iyi uygulamaları dikkate alın.

    • Üretimde kullandığınız tüm API özelliklerini önce EKM API test projenizde test edin.

    • EKM'yi tüm üretim API projelerinde aynı anda etkinleştirmek yerine kademeli olarak kullanıma 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ı.

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"
}

OCI

Etkin bir AES-256 anahtarı oluşturun ve OpenAI'a erişim izni verin. Anahtarda, değeri OpenAI Kuruluş Kimliğiniz olarak ayarlanmış serbest biçimli bir openai_organization_id etiketi bulunmalıdır. Kurulum adımları için bkz. Kurumsal Anahtar Yönetimi için OCI Vault'u yapılandırma.

Örnek istek:

  • type: dize - her zaman "oci"

  • purpose: dize - "ekm"; belirtilmediğinde varsayılan değer

  • name: dize - Yapılandırmanız için kolay anlaşılır bir ad

  • region: dize - Kasanızın ve anahtarınızın bulunduğu OCI bölgesi

  • vault_ocid: dize - Kasanızın tam OCID'si

  • key_ocid: dize - AES-256 anahtarınızın tam OCID'si

EKM için key_version_ocid göndermeyin.

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>"
}'

Örnek yanıt:

{
"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>"
}

İşlem başarılı olduğunda API, HTTP 200 döndürür. Döndürülen id değerini kaydedin ve proje oluştururken external_key_id olarak kullanın. Mevcut listeleme, getirme, doğrulama ve silme işlemleri OCI kayıtları için de geçerlidir.

PSP kurtarma için purpose: "psp_decryption" ve belirli bir sürümü tam olarak tanımlayan key_version_ocid değeri içeren ayrı bir RSA-3072 kaydı kullanın. psp_decryption_key_id değerini bu kaydın OpenAI kayıt kimliği olarak ayarlayın. OpenAI'ın bu RSA anahtarına ait meta veriler ve açık anahtarlar için yalnızca okuma erişimine ihtiyacı vardır. Tüm kurulum adımları için bkz. Asimetrik anahtarları ayarlama — OCI Vault.

Kuruluşunuza kayıtlı bir harici anahtarı silin

Not: Etkin bir proje veya çalışma alanı bu kaydı kullanırken silme işlemi engellenir. EKM için önce ilişkili API projelerini arşivleyin; bir çalışma alanıyla ilişkili EKM kaydı silinmeye karşı korunmaya devam eder. PSP kurtarma için kaydı silmeden önce, bu kayda başvuran tüm etkin projelerde psp_decryption_key_id değerini değiştirin veya temizleyin. Bir OpenAI kaydını silmek, bulut anahtarını silmez.

Ö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ı getirin

Amaç filtresi uygulanmadığında liste hem EKM hem de PSP kurtarma kayıtlarını içerir. Amaca göre filtrelemek için ?purpose=ekm veya ?purpose=psp_decryption kullanı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"
}

Harici bir anahtarı doğrulayın

OpenAI'ın bulut anahtarınıza hâlâ erişebildiğini kontrol etmek için doğrulamayı kullanın.

  • EKM için OpenAI, anahtarla şifreleme ve şifre çözme işlemlerini gerçekleştirebildiğini kontrol eder. İptal ve önbelleğe alma davranışı için bkz. anahtar yaşam döngüsü kılavuzu.

  • PSP kurtarma için OpenAI, kayıtlı sürümün açık anahtarını getirir ve saklanan anlık görüntüyle karşılaştırır. Doğrulamanın başarılı olması, kurtarma kimliğinizin şifre çözebildiğini teyit etmez. Doğrulamanın başarısız olması, saklanan açık anahtar anlık görüntüsünü kaldırmaz veya değiştirmez.

Bir kaydı GET ile getirmek, saklanan yapılandırmayı döndürür; bulut anahtarınıza erişimi yeniden kontrol etmez.

Ö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"
}

Mevcut bir projeyi harici anahtar kimliğiyle güncelleyin

Bu uç nokta, istek ve yanıta external_key_id parametresinin eklenmesi dışında mevcut Projeyi Güncelle uç noktasıyla aynıdır.

EKM iş yükleriniz için yeni API projeleri oluşturmanızı öneririz. Mevcut üretim projelerinizde EKM'yi kullanıma almadan önce aşağıdaki en iyi uygulamaları dikkate alın.

  • Üretimde kullandığınız tüm API özelliklerini önce EKM API test projenizde test edin.

  • EKM'yi tüm üretim API projelerinde aynı anda etkinleştirmek yerine kademeli olarak kullanıma 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
}

Bu makale yararlı oldu mu?