API 키
모델 호출에 필요한 키 발급과 보안 관리
자신의 키를 만들고 만료일, 월 한도와 IP 허용 목록을 설정하는 방법부터 역할별 관리 범위, 키 상태와 비활성화, 키 교체와 노출 대응까지 안내합니다.
페이지 목차
시작 전 확인
AI 게이트웨이 API 키는 현재 스페이스의 지원 모델을 호출할 때 사용하는 키입니다. 이 페이지의 절차로 만드는 키는 키를 만든 사람에게 연결됩니다. 이 페이지에서는 키와 키 값을 다음과 같이 구분합니다.
- 키
- 이름, 소유자, 상태, 만료일과 한도를 관리하는 대상입니다.
- 키 값
- API 요청의 인증에 사용하는 비밀 문자열입니다. 키 값이 노출되면 다른 사람이 그 키의 권한으로 모델을 호출할 수 있으므로 비밀번호처럼 취급합니다.
월별 사용량과 잔액을 외부 시스템에서 조회하려면 별도의 관리 API 키를 사용합니다. 모델 호출용 키와 혼용하지 마세요.
내 키와 전체 키 구분하기
AI 게이트웨이 > API 키에서 멤버(Member)와 스페이스 관리자(Admin) 모두 자신의 키를 만들 수 있습니다. 화면에서 보고 관리할 수 있는 키의 범위는 역할에 따라 다릅니다.
| 작업 | Admin | Member |
|---|---|---|
| 전체 키 보기 | 가능 | 표시되지 않음 |
| 내 키 보기 | 가능 | 가능 |
| 자신의 키 만들기 | 가능 | 가능 |
| 화면에 보이는 키 수정하기와 삭제하기 | 가능 | 가능 |
| 화면에 보이는 키 비활성화하기와 다시 활성화하기 | 가능 | 가능 |
| 다른 사용자가 만든 키 보기와 관리하기 | 가능 | 불가 |
Member는 자신이 만든 키만 보고 관리하며, 화면에는 내 키만 표시됩니다. Admin은 화면 상단에서 전체 키와 내 키를 전환하고, 전체 키에서 다른 사용자가 만든 키도 보고 관리할 수 있습니다. Admin이 다른 사용자의 키를 관리해도 키를 만든 사람은 바뀌지 않습니다.
구성원을 스페이스에서 제거하면 그 사람이 만든 활성 키는 삭제되므로, 그 키를 쓰던 사용처의 호출도 중단됩니다. 역할 변경과 구성원 제거가 키 관리에 미치는 영향은 구성원 권한에서 확인합니다.
키 만들기
생성 완료 화면을 닫은 뒤에는 같은 키 값을 다시 확인할 수 없습니다. 화면을 닫기 전에 키 값을 복사해 시크릿 저장소에 보관하세요. 값을 잃었다면 새 키를 만들고, 연결된 사용처에 저장한 키 값을 새 값으로 바꿉니다.
키 생성 열기
AI 게이트웨이 > API 키에서 키 생성을 선택합니다.
이름과 선택 설정 입력하기
사용처를 식별할 수 있는 이름을 입력합니다. 필요하면 월 한도와 만료일을 함께 설정합니다. 만료일은 설정한 뒤 바꾸거나 해제할 수 없으므로 만료일 설정 조건을 먼저 확인하세요. 월 한도를 입력하지 않으면 API 키 자체에는 월 한도가 설정되지 않습니다. 이 경우에도 자신에게 적용된 구성원 월 한도와 보유 유닛에 따른 제한은 유지됩니다.
키 값 복사하기
생성 완료 화면에서 키 값을 복사해 시크릿 저장소에 보관합니다.
키를 보관했다면 첫 API 호출에서 준비 사항을 확인하고 요청을 보내세요. 외부 도구에서 사용할 키라면 도구별 연결 안내에서 그 도구의 설정을 확인하세요.
키 상태 확인하기
AI 게이트웨이 > API 키 목록의 상태 열에서 각 키로 지금 모델을 호출할 수 있는지 확인합니다. 상태 필터에서 전체 상태, 활성, 비활성 또는 만료됨을 선택하면 해당 상태의 키만 볼 수 있습니다.
| 상태 | 뜻 | 할 수 있는 일 |
|---|---|---|
| 활성 | 모델을 호출할 수 있는 키입니다 | 수정, 비활성화, 삭제 |
| 비활성 | 키를 만든 사람이나 Admin이 비활성화한 키입니다. 새 호출에는 401 invalid_credentials가 반환됩니다 | 수정, 다시 활성화, 삭제 |
| 만료 | 만료일이 지난 키입니다. 호출에는 401 api_key_expired가 반환됩니다 | 삭제 |
삭제한 키는 목록에서 사라지고 복구할 수 없으며, 그 키로 보낸 호출은 거부됩니다.
키 비활성화하고 다시 활성화하기
노출이 의심될 때처럼 키의 사용을 바로 멈춰야 하면 키를 비활성화합니다. 키를 만든 사람은 자신의 키를, Admin은 전체 키에서 스페이스의 모든 키를 비활성화하고 다시 활성화할 수 있습니다.
- AI 게이트웨이 > API 키에서 키의 이름과 소유자를 확인하고 그 행의 관리 메뉴에서 비활성화를 선택합니다.
- 확인 창의 안내를 읽고 비활성화를 확정합니다.
- 목록에서 그 키의 상태가 비활성인지 확인합니다.
비활성화하면 그 키로 보내는 새 API 호출이 중단되고 401 invalid_credentials가 반환됩니다. 이미 처리 중인 요청은 취소되지 않습니다. 키 값, 이름, 만료일, IP 허용 목록과 월 한도는 그대로 유지됩니다.
비활성 키를 다시 사용하려면 같은 관리 메뉴에서 활성화를 선택합니다. 활성화하면 같은 키 값으로 새 호출을 보낼 수 있습니다. 다음 키는 다시 활성화하지 말고 새 키로 교체하세요.
- 만료된 키: 활성화를 선택할 수 없고 삭제만 할 수 있습니다. 만료된 키 대신 새 키 사용하기를 따릅니다.
- 노출된 키: 노출 대응에 따라 새 키로 교체하고 삭제합니다.
- 스페이스에서 제거된 구성원이 만든 키: 계속 필요한 사용처는 남는 구성원의 새 키로 전환하고 이전 키는 삭제합니다.
만료일과 월 한도 설정하기
만료일은 선택 사항입니다. 키를 만들 때 정하거나, 만료일이 없는 기존 키에 한 번 설정할 수 있습니다. KST 기준 오늘 또는 그 뒤 날짜를 고를 수 있습니다. 만료일을 지정하면 선택한 날짜의 23:59:59(KST)까지 키를 사용할 수 있고, 그 뒤에 보낸 요청부터 401 api_key_expired가 반환됩니다.
만료일을 고르는 화면에도 “만료일을 설정하면 이후 변경하거나 해제할 수 없습니다.”라는 안내가 표시됩니다. 설정한 날짜를 늦추거나 지울 수 없고, 만료된 키를 다시 활성화할 수도 없습니다. 키를 더 오래 사용해야 하면 만료일 전에 새 키로 사용처를 전환합니다.
만료일은 교체 시점을 강제하는 보조 수단이며 사용처 확인과 교체 절차를 대신하지 않습니다.
월 한도는 unit 단위로 설정합니다. 월 사용 한도를 설정할 수 있는 역할과 한도의 동작은 월 사용 한도에서 확인합니다. AI 게이트웨이 > API 키 화면 상단의 이번 달 내 사용량과 내 한도가 무엇을 뜻하는지도 같은 페이지에서 설명합니다.
| 설정 | 용도 |
|---|---|
| 이름 | 목록에서 사용처를 식별하는 데 사용합니다 |
| 만료일 | 지정한 날짜가 끝나면 키 사용을 제한합니다. 한 번 설정하면 바꾸거나 해제할 수 없습니다 |
| 월 한도 | API 키별 월 사용 한도를 unit 단위로 설정합니다 |
수정할 수 있는 키의 범위는 내 키와 전체 키 구분하기의 역할 표를 따릅니다. 만료일이 없는 기존 키에는 다음 순서로 만료일을 설정합니다.
- AI 게이트웨이 > API 키에서 키의 이름과 소유자를 확인하고 그 행의 관리 메뉴에서 수정을 선택합니다.
- 키 수정 화면에서 만료일을 지정한 뒤 수정을 선택합니다. 이미 만료일이 있는 키는 이 화면에 만료일 항목이 표시되지 않습니다.
- 수정 알림이 표시되면 목록의 만료일이 지정한 날짜인지 확인합니다.
만료된 키 대신 새 키 사용하기
만료된 키는 다시 활성화하거나 만료일을 바꿀 수 없고 삭제만 할 수 있습니다. 목록에서 만료 상태인 키를 쓰던 사용처는 다음 순서로 복구합니다.
- 새 키를 만듭니다. 기존 키를 만든 사람과 다른 사람이 새 키를 만들면 구성원 월 한도와 Batch 접근 범위가 달라지므로 새 키를 만들 사람을 먼저 정합니다.
- 만료된 키를 쓰던 서버, 배포 환경, 예약 작업과 외부 도구의 키 값을 새 값으로 바꿉니다. 각 사용처에서 새 키로 보낸 요청이 성공했는지 확인합니다.
- 모든 사용처의 전환을 확인했다면 만료된 키를 삭제합니다.
만료일이 다가온 키는 만료되기 전에 노출되지 않은 키 교체하기 절차로 미리 전환하면 호출이 중단되지 않습니다.
IP 허용 목록 설정하기
키를 사용하는 서버나 사무실의 IP가 정해져 있다면, 허용한 IP에서 보낸 요청만 통과하도록 키를 제한할 수 있습니다.
현재 서버의 출발지 IP를 추가하기 전에 허용 목록을 켜면 그 서버의 요청도 차단될 수 있습니다. 여러 서버가 같은 키를 사용한다면 모든 출발지 주소를 먼저 확인하세요.
보안 설정 열기
AI 게이트웨이 > API 키에서 대상 키를 찾습니다. IP 제한 열의 추가 또는 적용된 주소 개수 표시를 선택하면 보안 설정이 열립니다.
허용할 IP 추가하기
IP 허용 목록을 켜고 IP 추가를 선택합니다. 단일 IPv4와 IPv6 주소 또는
203.0.113.0/24같은 CIDR 대역을 입력할 수 있습니다.저장하고 호출 확인하기
현재 요청을 보내는 환경의 IP가 목록에 포함됐는지 확인한 뒤 저장을 선택합니다. 허용한 환경에서 API를 한 번 호출해 정상 응답을 확인합니다.
허용 목록의 상태에 따른 요청 결과는 다음과 같습니다.
| 상황 | 결과 |
|---|---|
| 허용 목록을 끈 키 | IP 제한이 적용되지 않습니다 |
| 허용 목록을 켠 키로 목록 밖의 IP에서 호출 | 403 ip_not_allowed가 반환됩니다 |
| 키 자체의 인증 실패 | 401이 반환됩니다 |
IP 차단과 인증 실패를 구분하는 방법은 오류 처리에서 확인합니다.
키 보관과 삭제 전 점검
키 값은 서버의 환경변수나 시크릿 저장소에 보관합니다. 키 값을 노출될 수 있는 곳에 보관하거나, 사용처를 확인하기 전에 키를 삭제하는 일이 없도록 다음 표를 먼저 확인합니다.
| 하지 말 것 | 대신 할 일 |
|---|---|
| 코드, Git 저장소, 채팅, 메일 본문 및 사용자가 값을 확인할 수 있는 클라이언트에 키 값을 직접 저장하기 | 서버의 환경변수나 시크릿 저장소에 보관합니다 |
| 실제 키가 포함된 기록에서 문자열만 지우기 | 아래 노출 대응을 먼저 따릅니다 |
| 연결된 사용처를 확인하지 않고 키 삭제하기 | 삭제한 키는 복구할 수 없으므로 사용처를 확인한 뒤 사용하지 않는 키만 삭제합니다 |
- 용도별 키 분리권장
운영 환경, 개발 환경과 외부 도구가 같은 키를 공유하지 않도록 사용처를 나누고, 키와 연결된 시스템을 기록합니다.
- 만료일과 월 한도권장
종료 시점이 있는 작업에는 만료일을 설정하고, 운영 환경에 연결하기 전에 월 사용 한도를 검토합니다. 만료일은 설정한 뒤 바꿀 수 없으므로 작업 종료 시점을 확인하고 정합니다.
- 저장소 비밀값 검사권장
코드 저장소를 사용한다면 커밋과 pull request, CI에서 비밀값 검사를 실행하기를 권장합니다. 키로 의심되는 값이 발견되면 병합과 배포를 멈추고 키 관리자에게 알립니다.
노출되지 않은 키 교체하기
상황에 맞는 절차를 먼저 고르세요.
| 하려는 일 | 따를 절차 |
|---|---|
| 노출되지 않은 키를 미리 교체 | 아래 단계 |
| 만료일이 다가온 키를 교체 | 만료일 전에 아래 단계를 시작 |
| 이미 만료된 키를 대체 | 만료된 키 대신 새 키 사용하기 |
| 노출된 키에 대응 | 관찰 기간을 기다리지 말고 노출 대응 |
| 퇴사 등으로 특정 사용자의 접근을 즉시 회수 | 즉시 접근 회수와 구성원 제거. 구성원 제거 전 점검은 키 정리와 별도로 진행 |
사용처와 정상 호출 주기 기록하기
키를 사용하는 서버, 배포 환경, 예약 작업과 외부 도구를 기록합니다. 각 사용처가 평소 얼마나 자주 호출하는지도 확인합니다. 하루보다 긴 주기로 실행하는 작업을 빠뜨리지 마세요.
새 키로 사용처 전환하기
먼저 새 키를 만들 사람을 정합니다.
- 기존 키를 만든 사람이 계속 스페이스에 참여한다면 그 사람이 새 키를 만듭니다.
- 구성원 제거 등으로 다른 사람이 새 키를 만들면 새 키의 사용량은 그 사람의 구성원 월 한도에 합산됩니다. Member가 볼 수 있는 키 사용량과, API로 접근할 수 있는 Batch 파일과 작업의 범위도 달라집니다. Admin이 만든 새 키가 다른 구성원의 기존 Batch에 접근할 수 있다고 가정하지 마세요.
AI 게이트웨이 > API 키에서 만드는 키는 개인 키입니다. Batch에 공유 키를 사용해 왔다면 공유 키로 제출한 작업의 접근 권한도 새 키로 이어지지 않습니다.
새 키에 필요한 설정을 확인한 뒤 각 사용처를 다음 순서로 전환합니다.
- 기록한 사용처의 키 값을 새 값으로 교체합니다.
- 그 사용처의 실제 프로세스나 도구에서 새 키로 보낸 요청이 성공했는지 확인하고 전환 완료를 기록합니다. 이 확인을 별도 cURL 호출로 대신하지 않습니다. 예약 작업처럼 바로 실행되지 않는 사용처는 다음 실행에서 확인합니다.
- 모든 사용처의 전환을 확인했다면 마지막 전환 완료 날짜와 시각을 KST로 기록합니다. 사용량 분석에서 그 KST 날짜를 선택하고 조회가 끝난 뒤 이전 키의 unit 사용량과 호출 수를 기록합니다. 조회한 시각도 함께 남깁니다. 기록한 값은 관찰 중 비교할 기준값으로 사용합니다.
새 키의 동작과 이전 키의 사용량 관찰하기
이 관찰은 사용처 누락을 찾기 위한 운영 절차입니다. 관찰 기간은 마지막 전환 뒤 최소 24시간과 사용처의 가장 긴 정상 호출 주기 가운데 더 긴 기간입니다. 이 기간 동안 다음 조건을 모두 확인합니다.
- 모든 사용처에서 새 키로 성공한 호출을 확인했습니다.
- 관찰 기간에 새 키의 사용량이 증가했습니다. 사용량 분석의 KST 날짜별 사용량과 호출 수를 실제 사용처의 성공한 호출 기록과 대조했습니다.
- 이전 키를 조회할 수 있는 범위에서 전환 당일의 unit 사용량과 호출 수가 기록한 기준값보다 늘지 않았고, 이후 날짜에도 이전 키의 사용이 나타나지 않았습니다. Admin은 스페이스의 모든 키를, Member는 자신의 키만 확인할 수 있습니다.
이전 키의 unit 사용량이나 호출 수가 한 번이라도 늘면 다음과 같이 대응합니다.
- 삭제를 보류하고 호출 기록과 사용처 목록을 대조해 누락됐거나 전환되지 않은 연결을 찾습니다.
- 추가 사용처를 새 키로 전환했다면 기준값을 다시 기록하고, 마지막 추가 전환 완료 시각부터 관찰을 다시 시작합니다.
사용량 값만 보고 이전 키를 삭제해도 된다고 판단하지 않도록 다음 표를 확인합니다.
하지 말 것 대신 할 일 집계 지연으로 보인다는 이유로 기준값만 고치고 삭제해도 된다고 판단하기 호출 시점이나 증가 원인을 확인하지 못하면 삭제를 보류합니다 조회가 끝나기 전에 보이는 값이나 빈 값, 0만으로 이전 키를 더 이상 사용하지 않는다고 판단하기 최근 호출의 집계 지연이나 조회 오류가 의심되면 사용량이 보이지 않거나 다를 때를 따라 다시 확인합니다 분석만으로 교체 완료를 판단하기 인증 실패처럼 분석에 나타나지 않는 요청이 있으므로 애플리케이션 로그와 오류 알림도 함께 확인합니다 이전 키 삭제하고 오류 확인하기
삭제한 키는 복구할 수 없습니다이전 키를 삭제하기 전에 아래 두 항목을 모두 확인하세요.
- 관찰 기간 동안 위 조건을 모두 확인했습니다. 기간이 지났더라도 예약 작업이 실행되지 않았거나 조건을 확인하지 못했다면 삭제를 보류합니다. 아직 실행되지 않은 작업은 다음에 실행될 때 새 키로 정상 호출하는지 확인하세요.
- 진행 중이거나 결과를 아직 받지 않은 Batch가 있다면 Batch ID를 기록하고, 결과를 받을 경로를 콘솔과 API 키의 접근 범위에서 확인합니다. 키 종류나 접근 범위를 알 수 없다면 플랫폼 내 문의 기능에 Batch ID와 키 이름을 남겨 확인을 요청합니다. 키 값은 보내지 않습니다.
모두 확인했다면 이전 키를 삭제합니다. 삭제 후에도 각 사용처의 로그와 오류 알림에서
401인증 실패가 발생하지 않는지 확인합니다. 이전 키를 사용하는 사용처가 남아 있다면 새 키로 전환합니다.
노출된 API 키 대응
키가 노출됐다면 되도록 빨리 다음 순서로 대응합니다.
교체가 끝날 때까지 노출된 키를 활성 상태로 두지 마세요. 비활성화하면 그 키의 새 호출이 바로 중단됩니다. 키 값을 문의 내용에 포함하지 마세요. 다른 사용자가 만든 키라면 Admin에게 즉시 알립니다.
노출된 키 즉시 비활성화하기
AI 게이트웨이 > API 키에서 노출된 키의 이름과 소유자를 확인한 뒤 역할에 따라 대응합니다.
- 자신의 키라면 내 키에서 그 행의 관리 메뉴를 열고 즉시 비활성화합니다.
- 다른 사용자의 키이고 자신이 Admin이라면 전체 키에서 즉시 비활성화합니다.
- 다른 사용자의 키이고 자신이 Member라면 Admin에게 즉시 비활성화를 요청합니다.
목록에서 그 키의 상태가 비활성인지 확인하고 비활성화한 시각을 KST로 기록합니다. 이미 처리 중이던 요청은 취소되지 않습니다. 노출된 키는 다시 활성화하지 않습니다.
새 키 만들고 사용처 교체하기
개인 키는 스페이스에 계속 참여할 사람이 새로 만듭니다.
- 기존 키를 만든 사람이 계속 스페이스에 참여한다면 그 사람이 새 키를 만듭니다.
- 그 사람이 더 이상 참여할 수 없다면 스페이스에 남는 구성원이 자신의 키를 만듭니다.
기존 키를 만든 사람과 다른 사람이 새 키를 만들면, 새 키를 만든 사람의 구성원 월 한도와 조회 범위가 적용됩니다. 이전 키로 제출한 Batch 파일과 작업의 접근 권한이 새 키로 이어진다고 가정하지 마세요.
진행 중이던 Batch의 결과를 새 키로 조회할 수 없더라도 다시 제출하지 마세요. 접근 오류만으로 기존 작업이나 파일이 없어졌다고 판단하지 않습니다. 기존 Batch ID로 결과를 받을 경로는 콘솔과 API 키의 접근 범위에서 확인합니다. 확인할 수 없으면 플랫폼 내 문의 기능에 Batch ID를 남겨 문의합니다. 키 값은 보내지 않습니다.
새 키에 노출된 키와 구분되는 이름을 입력하고, 필요한 만료일과 월 한도를 설정합니다. 연결된 서버, 배포 환경 및 외부 도구에 저장한 키 값을 새 키 값으로 교체합니다. 그다음 각 사용처에서 새 키로 요청을 보내 정상 응답을 받는지 확인합니다.
노출 이후 사용량 확인하기
사용량 분석에서 노출된 API 키의 호출 수와 누적 사용량을 확인합니다. 알 수 없는 사용이 보이거나 비활성화한 뒤에도 사용이 의심되면 렛서 플랫폼에 로그인한 뒤 플랫폼 내 문의 기능에 스페이스, 키 이름, 비활성화 시각과 의심 시각을 남깁니다. 키 값은 보내지 않습니다.
노출된 키 삭제하기
모든 사용처를 새 키로 전환하고 노출 이후의 사용량 확인을 마쳤다면 노출된 키를 삭제합니다. 삭제한 키는 복구할 수 없습니다. 결과를 아직 받지 않은 Batch가 있다면 삭제하기 전에 콘솔과 API 키의 접근 범위에서 결과를 받을 경로를 확인합니다.
문제 해결
| 증상 | 확인할 것 |
|---|---|
401 invalid_credentials 또는 401 missing_credentials가 반환됩니다 | 키 값과 요청 헤더를 확인합니다. 목록에서 그 키가 비활성 상태이거나 삭제되지 않았는지도 확인합니다 |
401 api_key_expired가 반환됩니다 | 키의 만료일이 지났습니다. 만료된 키 대신 새 키 사용하기를 따릅니다 |
| 키 수정 화면에 만료일 항목이 없습니다 | 이미 만료일이 설정된 키입니다. 만료일은 바꾸거나 해제할 수 없으므로 더 오래 사용하려면 만료일 전에 새 키로 전환합니다 |
403 ip_not_allowed가 반환됩니다 | 현재 요청의 출발지 IP를 확인하고 키의 IP 허용 목록에 주소 또는 대역을 추가합니다 |
429 policy_limit_exceeded 또는 429 usage_limit_exceeded가 반환됩니다 | 한도에 도달했을 때에서 오류 코드별 확인 순서를 따릅니다 |
| 저장하지 않고 완료 화면을 닫았습니다 | 새 키를 만듭니다. 값을 잃은 키가 목록에 남아 있으면 사용처를 확인한 뒤 삭제합니다 |