요약

액세스

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을 적용하기 전에 다음 모범 사례를 참고하세요.
- 운영 환경에서 사용하는 모든 API 기능을 먼저 테스트용 EKM API 프로젝트에서 검증하세요.
- 모든 운영 API 프로젝트에 한 번에 EKM을 적용하기보다는 점진적으로 배포하세요.

조직 수준 엔드포인트

조직에 외부 키 등록

AWS

샘플 요청

type: string - 항상 “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: 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 키 링 이름
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 - 항상 "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"
}

조직에 등록된 외부 키 삭제

참고: 외부 키는 활성 프로젝트와 연결되어 있지 않은 경우에만 삭제할 수 있습니다. 활성 프로젝트와 연결되어 있는 경우 해당 프로젝트를 먼저 아카이브해야 합니다.

샘플 요청

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를 사용하여 기존 프로젝트 업데이트

샘플 요청

조직의 모든 프로젝트 나열

샘플 요청

샘플 응답

이 문서가 도움이 되었나요?