요약
액세스
EKM 엔드포인트는 관리 API에서 관리자 API 키를 통해 액세스할 수 있습니다. https://platform.openai.com/settings/organization/admin-keys (일반 API 키는 사용하지 마세요.) 관리자 API 키는 조직 소유자에게 제공됩니다.
외부 키를 생성하거나 삭제하려면
api.external_keys.write를 사용하고, 외부 키를 조회하거나 검증하려면api.external_keys.read를 사용합니다. 하나의 키가 읽기와 쓰기 작업을 모두 수행해야 하는 경우에만 두 권한이 모두 필요합니다.현재는 해당 엔드포인트를 사용할 수 있도록 조직에 기능 플래그를 활성화해야 합니다. 기존의 프로젝트 목록 엔드포인트에서 external_key_id가 반환되면 기능 플래그가 활성화된 것입니다(https://api.openai.com/v1/organization/projects).
사용
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를 전달하여 프로젝트 수준에서 활성화됩니다 엔드포인트에 게시해 이 작업을 수행할 수 있습니다.
제한 사항
먼저 관리 API를 통해 새 프로젝트에서 EKM을 테스트해야 합니다.
EKM 워크로드를 위해 새로운 프로젝트를 생성하는 것을 권장합니다. 기존 프로젝트에서 EKM을 사용하려면 기능 플래그를 활성화해 드릴 수 있습니다. 기존 운영 프로젝트에 EKM을 적용하기 전에 다음 모범 사례를 참고하세요.
먼저 테스트용 EKM API 프로젝트에서 프로덕션 환경에서 사용하는 모든 API 기능을 테스트하세요.
모든 프로덕션 API 프로젝트에 EKM을 한꺼번에 구성하는 대신 점진적으로 적용하세요.
조직 수준 엔드포인트
조직에 외부 키 등록
AWS
요청의 예시:
type: 문자열 - 항상 “aws”
name: string - 구성에 대한 식별하기 쉬운 이름
role_arn: string - OpenAI가 클라우드에서 사용할 Role ARN
kms_arn: string - 사용자가 관리하는 마스터 키의 KMS 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: 문자열 - 항상 "gcp",
name: string - 구성에 대한 식별하기 쉬운 이름
workload_identity_project_number: 문자열 - 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 키 링 이름
kms_key_name: string - KMS 마스터 키 이름
kms_key_location: string - KMS 마스터 키가 위치한 리전
KMS가 OpenAI의 워크로드 아이덴티티를 등록한 GCP 프로젝트와 다른 프로젝트에 있는 경우, https://console.developers.google.com/apis/api/cloudkms.googleapis.com/overview에서 OpenAI의 워크로드 아이덴티티가 등록된 프로젝트에서 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 - always "azure",
name: string - 구성에 대한 식별하기 쉬운 이름
tenant_id: string - Azure 테넌트 UUID
vault_uri: string - 사용자가 관리하는 마스터 키가 포함된 Azure vault URI
key_name: string - 사용자가 관리하는 Azure Key Vault 마스터 키 이름
형식은 <org-xxx>--이어야 합니다.
여기서 org-xxx 는 https://platform.openai.com/settings/organization/general에서 확인할 수 있는 OpenAI 조직 ID입니다.
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을 적용하기 전에 다음 모범 사례를 참고하세요.
먼저 테스트용 EKM API 프로젝트에서 프로덕션 환경에서 사용하는 모든 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
}