API 키
자신의 AI 게이트웨이 API 키를 만들고 사용할 네트워크와 수명 주기를 안전하게 관리하세요.
역할별 조회 범위와 키 생성, IP 허용 목록, 만료 및 삭제 절차를 다룹니다.
시작 전 확인
AI 게이트웨이 API 키는 현재 스페이스의 지원 모델을 호출할 때 사용하는 비밀 인증값입니다. 키가 노출되면 다른 사람이 해당 키의 권한으로 모델을 호출할 수 있으므로 비밀번호처럼 취급합니다. AI 게이트웨이 > API 키에서 Member와 Admin 모두 자신의 키를 만들 수 있습니다.
역할별 키 조회 범위
| 작업 | Admin | Member |
|---|---|---|
전체 키 보기 | 가능 | 표시되지 않음 |
내 키 보기 | 가능 | 가능 |
| 자신의 키 만들기 | 가능 | 가능 |
| 화면에 보이는 키 수정 및 삭제 | 가능 | 가능 |
Member는 자신이 만든 키만 보고 관리합니다. Admin은 전체 키에서 다른 사용자가 만든 키도 보고 관리할 수 있습니다. 구성원 역할 변경 및 제거와 키 정리는 별도 작업이므로 AI 게이트웨이 구성원의 변경 전 점검을 따릅니다.
키 만들기
키 생성 열기
AI 게이트웨이 > API 키에서 키 생성을 선택합니다.
이름과 선택 설정 입력하기
사용처를 알아볼 수 있는 이름을 입력합니다. 필요하면 월 한도와 만료일을 함께 지정합니다. 월 한도를 비워 두면 제한 없이 생성됩니다.
키 값 복사하기
생성 완료 화면에서 키 값을 복사해 시크릿 저장소에 보관합니다. 키 원문은 이 화면에서 한 번만 확인할 수 있습니다.
생성 완료 화면을 닫은 뒤에는 같은 키 값을 다시 확인할 수 없습니다. 값을 잃었다면 새 키를 만들고 사용처를 교체합니다.
만료일과 월 한도 설정하기
월 사용 한도의 권한과 동작은 한도에서 확인합니다.
만료일을 지정하면 선택한 날짜의 한국시간 23:59:59까지 키를 사용할 수 있고, 그 뒤 요청부터 401 api_key_expired가 반환됩니다.
| 설정 | 용도 |
|---|---|
| 이름 | 목록에서 사용처를 식별합니다 |
| 만료일 | 지정한 시점 이후 키 사용을 제한합니다 |
| 월 한도 | API 키별 월 사용 상한을 unit 단위로 설정합니다 |
IP 허용 목록 설정하기
키를 사용하는 서버나 사무실의 IP가 정해져 있다면, 허용한 IP에서 보낸 요청만 통과하도록 제한할 수 있습니다.
보안 설정 열기
AI 게이트웨이 > API 키에서 대상 키를 찾습니다.
IP 제한열의 추가 또는 적용된 주소 개수 표시를 선택하면 보안 설정이 열립니다.허용할 IP 추가하기
IP 허용 목록을 켜고 IP 추가를 선택합니다. 단일 IPv4와 IPv6 주소 또는
203.0.113.0/24같은 CIDR 대역을 입력할 수 있습니다.저장하고 호출 확인하기
현재 요청을 보내는 환경의 IP가 목록에 포함됐는지 확인한 뒤 저장을 선택합니다. 허용한 환경에서 API를 한 번 호출해 정상 응답을 확인합니다.
현재 서버의 출발지 IP를 추가하기 전에 허용 목록을 켜면 그 서버의 요청도 차단될 수 있습니다. 여러 서버가 같은 키를 쓴다면 모든 출발지 주소를 먼저 확인하세요.
허용 목록을 끄면 IP 제한을 적용하지 않습니다. 허용 목록을 켠 키를 목록 밖의 IP에서 호출하면 403 ip_not_allowed가 반환됩니다. 키 자체의 인증 실패는 401이므로 오류 처리에서 두 원인을 구분합니다.
키 보관, 교체 및 삭제
- 안전한 저장 위치
서버의 환경변수나 시크릿 매니저에 보관합니다. 코드, Git 저장소, 채팅, 메일 본문 및 사용자가 값을 확인할 수 있는 클라이언트에는 직접 넣지 않습니다.
- 용도별 키 분리
운영, 개발 및 외부 도구가 같은 키를 공유하지 않도록 사용처를 나누고, 키와 연결된 시스템을 기록합니다.
- 만료일과 월 한도
종료 시점이 있는 작업에는 만료일을 설정하고, 운영 환경에 연결하기 전에 월 사용 한도를 검토합니다.
- 저장소 비밀값 검사
commit, pull request 및 CI에서 secret scanning을 실행합니다. 키로 의심되는 값이 발견되면 병합 및 배포를 차단하고 키 관리자에게 알립니다. 실제 키가 포함됐다면 기록에서 문자열만 지우지 말고 아래 노출 대응을 먼저 수행합니다.
- 미사용 키 삭제
연결된 사용처를 확인한 뒤 사용하지 않는 키를 삭제합니다. 삭제한 키는 복구할 수 없습니다.
정기 교체가 필요한 키는 연결된 사용처를 먼저 기록하고, 새 키를 만든 뒤 사용처를 순서대로 교체해 동작을 확인합니다. 모든 사용처가 새 키를 쓰면 이전 키를 삭제하고 사용량 분석에서 예상한 키만 호출되는지 확인합니다. 만료일은 교체 시점을 강제하는 보조 수단이며 사용처 확인과 교체 절차를 대신하지 않습니다.
노출된 API 키 대응
키가 노출되었다면 가능한 한 짧은 시간 안에 다음 순서로 대응합니다.
키 값을 문의 내용에 붙여 넣지 마세요. 다른 사용자가 만든 키라면 스페이스 Admin에게 즉시 알립니다.
노출된 키 즉시 삭제하기
AI 게이트웨이 > API 키에서 노출된 키의 이름과 소유자를 확인하고 즉시 삭제합니다. 삭제하면 해당 키를 쓰는 요청은 중단되지만, 교체가 끝날 때까지 노출된 키를 유효하게 두지 않습니다.
새 키 만들고 사용처 교체하기
삭제한 키와 구분되는 이름으로 새 키를 만들고 필요한 만료일과 월 한도를 설정합니다. 연결된 서버, 배포 환경 및 외부 도구에서 새 키로 교체해 동작을 확인합니다.
노출 이후 사용량 확인하기
사용량 분석에서 해당 API 키의 호출 수와 누적 사용량을 확인합니다. 알 수 없는 사용이 보이면 로그인한 렛서 플랫폼의 문의 기능에 스페이스, 키 이름과 의심 시각을 남깁니다.