API 키는 요청을 인증하는 데 쓰는 비밀 자격 증명입니다. 서비스 계정은 애플리케이션이나 자동화된 워크로드가 사용할 수 있는 비사용자 ID입니다. 서비스 계정은 API 키를 소유할 수 있습니다. 이때 서비스 계정은 인증 주체이고 API 키는 해당 계정의 자격 증명입니다.
개인 개발 작업에는 본인 소유의 프로젝트 키를 사용하세요. 권한과 수명 주기를 독립적으로 관리해야 하는 애플리케이션이나 자동화 작업에는 서비스 계정을 사용하세요. 관리자 API를 통해 조직을 관리할 때는 관리자 API 키를 사용하세요.
적절한 ID 선택하기
| 워크로드 | ID 및 자격 증명 | 선택 이유 |
|---|---|---|
| 개인 로컬 환경에서 개발하거나 기능을 시험하는 작업 | 본인의 사용자 계정과 프로젝트 API 키 | 요청에 본인의 프로젝트 접근 권한이 적용됩니다. |
| 배포된 애플리케이션, 예약 작업 또는 CI 워크플로우 | 프로젝트 서비스 계정과 해당 계정의 API 키 | 워크로드가 개발자 개인과 별도의 ID를 사용합니다. |
| OpenAI가 지원하는 ID 공급자를 사용하는 워크로드 | 워크로드 ID 페더레이션을 사용하는 프로젝트 서비스 계정 | 워크로드가 수명이 긴 OpenAI API 키를 저장하지 않고도 인증할 수 있습니다. |
| 프로젝트를 생성하거나 해당 프로젝트의 서비스 계정과 키를 관리하는 자동화 작업 | 관리자 API 키 | 조직 관리에는 별도의 관리용 엔드포인트와 권한을 사용합니다. |
사용자 소유 키에는 소유자의 접근 권한이 적용됩니다. 개발자 한 명의 키를 팀이 공유하거나 해당 개발자의 ID를 프로덕션 애플리케이션의 영구 ID로 사용하지 마세요.
서비스 계정은 프로젝트에 속합니다. 각 워크로드에 해당 프로젝트 내에서 필요한 ID와 접근 권한을 부여하세요. 프로젝트를 분리하면 애플리케이션이나 환경별로 리소스, 구성원, 사용량을 분리할 수 있습니다. 한 프로젝트 내에서 서비스 계정을 나누면 프로젝트를 추가로 만들지 않고도 워크로드를 구분할 수 있습니다.
권한과 적용 범위 이해하기
API 키로 수행할 수 있는 작업은 키의 권한과 소유자의 권한에 따라 결정됩니다. 키의 권한 범위를 설정해 허용되는 작업을 제한할 수 있지만, 사용자나 서비스 계정에 없는 권한을 키에 부여할 수는 없습니다. 제한이 없는 키도 소유자에게 실제로 부여된 권한 내에서만 작동합니다.
서비스 계정에는 해당 워크로드에 필요한 역할만 할당한 다음, 필요한 경우 키의 권한 범위도 제한하세요. 권한 부여 방식은 권한 및 역할을 참고하세요. ID를 생성하고 사용자 지정 역할을 할당한 뒤 권한 범위가 지정된 키를 발급하는 구성 예시는 Terraform으로 서비스 계정 구성하기를 참고하세요.
관리자 API 키와 프로젝트 워크로드용 키는 용도가 다릅니다. 관리자 자격 증명은 리소스를 프로비저닝하고 관리하는 신뢰할 수 있는 서비스에 보관하세요. 애플리케이션이 모델에 요청을 보낼 때는 프로젝트의 서비스 계정 자격 증명을 사용하세요.
프로젝트 및 키 관리 자동화하기
고객을 위해 프로젝트를 프로비저닝하는 애플리케이션에서는 프로젝트 서비스 계정을 사용해 각 워크로드에 ID를 부여할 수 있습니다. 이 ID는 프로비저닝을 실행하는 개발자에게 종속되지 않습니다. 프로비저닝 서비스는 관리자 API로 프로젝트와 해당 서비스 계정을 관리하고, 프로비저닝된 애플리케이션은 자체 프로젝트 자격 증명을 사용합니다.
관련 관리 작업은 다음과 같습니다.
| 작업 | 용도 |
|---|---|
| 프로젝트 생성 | 워크로드의 리소스와 서비스 계정을 소유할 프로젝트를 생성합니다. |
| 서비스 계정 생성 | 해당 프로젝트에 워크로드의 ID를 생성합니다. create_service_account_only 옵션을 사용하면 기본 역할이나 초기 API 키 없이 서비스 계정을 생성합니다. |
| 서비스 계정 API 키 생성 | 기존 서비스 계정에 키를 발급하고 필요에 따라 키의 권한 범위와 만료 시점을 설정합니다. |
| 프로젝트 API 키 관리 | 서비스 계정 키를 포함한 기존 프로젝트 키의 목록을 확인하거나 개별 키를 조회, 업데이트 또는 폐기합니다. |
프로젝트 API 키 관리 엔드포인트로는 다른 사용자를 대신해 해당 사용자가 소유할 프로젝트 키를 생성할 수 없습니다. 프로그래밍 방식으로 키를 생성하려면 서비스 계정과 해당 계정의 키 생성 엔드포인트를 사용하세요.
기본 역할 없이 서비스 계정을 생성하면 해당 계정에는 모델에 요청을 보낼 권한이 없습니다. 자격 증명을 사용하기 전에 필요한 권한을 부여하세요. 키 생성에는 조직과 프로젝트의 키 정책도 적용되며, 서비스 계정으로 이러한 정책을 우회할 수 없습니다.
수명 주기 전반에 걸쳐 자격 증명 관리하기
API는 서비스 계정 키를 생성할 때만 키의 전체 값을 반환합니다. 이 값을 비밀 관리 도구에 저장한 뒤 서버에서 워크로드에 제공하세요. 브라우저 코드, 모바일 앱, 소스 관리 시스템, 로그, 고객에게 보내는 응답에 비밀 키를 포함하지 마세요.
조직과 프로젝트의 정책에 맞는 만료 시점을 설정하세요. 키를 교체하려면 새 키를 발급하고 워크로드가 새 키를 사용하도록 업데이트하세요. 워크로드가 정상적으로 작동하는지 확인한 다음 기존 키를 폐기하세요. 키를 교체해도 서비스 계정의 ID는 그대로 유지할 수 있습니다.
워크로드의 역할이 바뀌면 접근 권한을 검토하고, 워크로드 운영을 종료하면 자격 증명을 폐기하세요. 키 관리 및 만료 정책은 프로덕션 API 키 지침을 참고하세요. API 키를 저장하지 않고 인증하는 방법은 워크로드 ID 페더레이션을 참고하세요.