まとめ

アクセス

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 のワークロードアイデンティティを登録した12桁の 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 のワークロード ID を登録した 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"
}

組織に登録されている外部キーを削除する

注意： 外部キーは、アクティブなプロジェクトに関連付けられていない場合にのみ削除できます。アクティブなプロジェクトに関連付けられている場合は、まずそのプロジェクトをアーカイブする必要があります。

要求の例

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

[制約あり] 外部キー 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
}

Management API の EKM（外部キー）

まとめ

アクセス

使用方法

制約事項

組織レベルのエンドポイント

組織に外部キーを登録する

AWS

要求の例

応答の例

GCP

要求の例

応答の例

Azure

要求の例

応答の例

組織に登録されている外部キーを削除する

要求の例

応答の例

組織に登録されている外部キーを取得する

要求の例

応答の例

外部キーを検証する

要求の例

応答の例

プロジェクトレベルのエンドポイント

外部キー ID を使用して新規プロジェクトを作成する

要求の例

応答の例

[制約あり] 外部キー ID を使用して既存のプロジェクトを更新する

要求の例

組織内のすべてのプロジェクトを一覧表示する

要求の例

応答の例

この記事は役に立ちましたか？