まとめ
アクセス
EKM エンドポイントには、管理者 API キー を使用して Management API 経由でアクセスできます。https://platform.openai.com/settings/organization/admin-keys（通常の API キーは使用しないでください）。管理者 API キーは、組織の所有者のみが利用できます。
api.external_keys.writeを使用して外部キーを作成または削除し、api.external_keys.readを使用して外部キーを一覧表示または検証します。単一のキーに両方のスコープが必要になるのは、読み取り操作と書き込み操作の両方を実行する必要がある場合のみです。現時点では、これらのエンドポイントを組織で利用できるよう、機能フラグを設定する必要があります。既存のプロジェクト一覧取得エンドポイント（ https://api.openai.com/v1/organization/projects ）から external_key_id が返される場合、機能フラグが有効になっていることがわかります。
使用方法
EKM 設定は、新しいエンドポイント https://api.openai.com/v1/organization/external_keysを介して、組織レベルで 登録されます。
EKM 設定を登録すると、extkey_xxxx 形式の external_key_id が返されます。
EKM 設定は、既存のプロジェクト作成エンドポイント（ https://api.openai.com/v1/organization/projects ）の本文に external_key_id を渡すことで、 プロジェクト レベルで 有効化 されますエンドポイント。
制約事項
まず、Management API を使用して新規プロジェクトで EKM をテストする必要があります。
EKM ワークロード用に新規プロジェクトを立ち上げることを推奨します。ただし、既存のプロジェクトで EKM を使用したい場合は、機能フラグに追加できます。既存の本番環境プロジェクトに EKM を展開する前に、以下のベストプラクティスをご確認ください。
本番環境で使用する API のすべての機能を、まずはテスト用の EKM API プロジェクトでテストしてください。
すべての本番環境 API プロジェクトに一度に EKM を展開せず、段階的に展開してください。
組織レベルのエンドポイント
組織に外部キーを登録する
AWS
要求の例：
type：string - 常に「aws」
name：string - 設定のわかりやすい名前
role_arn：string - OpenAI がクラウド環境で引き受けるロール ARN
kms_arn：string - お客様が管理するマスターキーのキー管理システム ARN
external_id：string - 組織 ID または API プロジェクト 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>"
}'応答の例：
{
"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
要求の例：
type：string - 常に「gcp」、
name：string - 設定のわかりやすい名前
workload_identity_project_number：string - OpenAI のワークロード ID を登録した GCP プロジェクトの数値プロジェクト番号
workload_identity_pool_id：string - OpenAI 用に登録したワークロードアイデンティティプロバイダーを含むプール
workload_identity_provider_id：string - OpenAI 用に登録したワークロードアイデンティティプロバイダー
audience：string - OpenAI が GCP STS を介してロールを引き受ける際にトークンに含めるオーディエンス
kms_project_id：string - KMS が存在する GCP プロジェクトの名前
kms_key_ring_name：string - お客様が管理するマスターキーを含むキー管理システムのキーリング
kms_key_name：string - キー管理システムのマスターキーの名前
kms_key_location：string - キー管理システムのマスターキーが格納されているリージョン
KMS が OpenAI の Workload Identity を登録した GCP プロジェクトとは別のプロジェクトに存在する場合は、https://console.developers.google.com/apis/api/cloudkms.googleapis.com/overview にアクセスして、OpenAI のワークロード ID を含むプロジェクトで少なくとも KMS が有効になっていることを確認してください。
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"
}'応答の例：
{
"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
要求の例：
type：string - 常に「azure」
name：string - 設定のわかりやすい名前
tenant_id：string - Azureテナントの UUID
vault_uri：string - お客様が管理するマスターキーを含む Azure ボールトの URI
key_name：string - お客様が管理する Azure Key Vault のマスターキーの名前。
形式は <org-xxx>--<any_name> とする必要があります。
ここでの org-xxx は OpenAI 組織 ID であり、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"
}'応答の例：
{
"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"
}組織に登録されている外部キーを削除する
注意： 外部キーは、アクティブな API プロジェクトまたはワークスペースに関連付けられていない場合にのみ削除できます。アクティブな API プロジェクトに関連付けられている場合は、まずそのプロジェクトをアーカイブしてください。ワークスペースに関連付けられている場合、そのキーは削除できません。
要求の例
curl -X DELETE \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys/extkey_xxxx"応答の例
{
"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>"
}組織に登録されている外部キーを取得する
要求の例
curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys"応答の例
{
"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"
}外部キーを検証する
このエンドポイントを使用して、複数の項目を確認できます：
変更後も、外部クラウド構成は OpenAI で引き続き有効です（成功応答が表示されます）。
キーの失効処理は正常に行われており、OpenAI で処理中です。1時間のキャッシュ TTL が切れると、失効が反映されます（エラー応答が表示されます）。
要求の例
curl -X POST -H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys/extkey_xxx/validate"応答の例
{
"status": "success"
}そうでない場合、クラウドプロバイダーでエラーが発生した可能性があります。
プロジェクトレベルのエンドポイント
外部キー ID を使用して新規プロジェクトを作成する
これは既存のプロジェクト作成エンドポイントと同じですが、要求と応答に external_key_id パラメータが追加されています。
要求の例
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"
}'応答の例
{
"object": "organization.project",
"id": "proj_xxxxx",
"name": "Some Project",
"external_key_id": "extkey_xxxx",
"created_at": 1740012721,
"archived_at": null,
"status": "active"
}[制約あり] 外部キー ID を使用して既存のプロジェクトを更新する
これは既存のプロジェクト更新エンドポイントと同じですが、要求と応答に external_key_id パラメータが追加されています。
EKM ワークロード用に新規 API プロジェクトを立ち上げることを推奨します。既存のすべての API プロジェクトで EKM を使用したい場合は、アカウントディレクターまでお問い合わせください。機能フラグに追加します。既存の本番環境プロジェクトに EKM を展開する前に、以下のベストプラクティスをご確認ください。
本番環境で使用する API のすべての機能を、まずはテスト用の EKM API プロジェクトでテストしてください。
すべての本番環境 API プロジェクトに一度に EKM を展開せず、段階的に展開してください。
要求の例
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"
}'組織内のすべてのプロジェクトを一覧表示する
これは既存のエンドポイントと同じですが、API 応答に external_key_id が追加されています。
要求の例
curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/projects"応答の例
{
"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
}