관리 API 인증
관리 API 키로 스페이스 데이터에 접근하기
Admin의 키 발급과 재발급, Bearer 인증 헤더, 키 보관과 접근 회수 절차를 안내합니다.
페이지 목차
두 API 키 구분하기
스페이스의 월별 사용량과 유닛 잔액을 조회하려면 관리 API 키(Management Key, mk_...)를 사용합니다. 사내 모니터링, 사용 기록 저장 또는 정산 배치에서 이 데이터를 조회할 때 필요한 키입니다.
모델 추론에 사용하는 AI 게이트웨이 API 키로는 관리 API를 호출할 수 없습니다. 두 키는 용도, 요청 주소, 원문을 다시 복사할 수 있는 조건이 다릅니다.
- 관리 API 키(
mk_...): 월별 사용량과 유닛 잔액을 조회합니다. 요청 주소는https://openapi.letsur.ai/v1입니다. Admin이 스페이스 관리 > 관리 API에서 원문을 다시 복사할 수 있습니다. - AI 게이트웨이 API 키: 모델 추론에 사용합니다. 요청 주소는 AI 게이트웨이 기본 URL입니다. 원문은 처음 생성할 때만 표시됩니다.
두 키는 호출하는 호스트와 권한이 다르므로 같은 값이나 같은 변수 이름으로 재사용하지 마세요. 모델을 호출하려면 AI 게이트웨이 인증과 기본 URL에 따라 키와 요청 주소를 설정합니다.
관리 API 키 준비하기
조회할 스페이스의 Admin만 관리 API 키를 발급, 복사, 재발급할 수 있습니다.
Member에게는 접근 권한 없음 안내가 표시되며 키 값과 관리 기능은 제공되지 않습니다. Member라면 현재 스페이스의 Admin에게 관리 API 연동에 필요한 키 준비를 요청하세요. 스페이스 역할과 권한에서 역할을 확인할 수 있습니다.
조회할 스페이스 확인하기
- 서버에서 관리 API를 호출하면 관리 API 키가 연결된 스페이스의 데이터가 조회됩니다. 요청에 스페이스를 별도로 지정하지 않습니다.
- 여러 스페이스의 데이터를 조회한다면 각 스페이스에서 발급한 키를 구분해 보관하고, 요청할 때 대상 스페이스에 맞는 키를 선택합니다.
화면에서 키 발급하고 복사하기
관리 API 화면 열기
조회할 스페이스를 선택한 뒤 스페이스 관리 > 관리 API를 엽니다.
키 발급하기
API 키 영역에 “아직 발급된 API 키가 없습니다.”라고 표시되면 발급하기를 선택합니다. 이미 키가 있으면 새로 발급하지 않고 표시된 키를 사용합니다.
키 복사하기
관리 API 키를 브라우저 코드, 공개 저장소나 로그에 남기지 마세요키 옆의 복사를 선택합니다. 복사한 값은 서버의 비밀 변수나 비밀 관리 도구에 보관합니다.
결과 확인하기
키를 발급했다면 발급 성공 알림이 표시된 뒤 가려진 키 값과 발급일을 확인합니다. 키를 복사했다면 복사됨 표시 또는 복사 완료 알림을 확인합니다.
첫 조회 요청 보내기
모든 관리 API 요청을 https://openapi.letsur.ai/v1 아래의 엔드포인트로 보내고, Authorization 헤더에 관리 API 키를 포함합니다.
Authorization: Bearer mk_...다음은 cURL로 월별 사용량을 조회하는 예시입니다. month=2026-08을 조회할 KST 월(YYYY-MM)로 바꾸세요. month를 생략하면 현재 월이 조회됩니다.
실행 환경의 시크릿 설정으로 LETSUR_MANAGEMENT_KEY를 준비합니다. 실제 키를 예제 코드에 직접 입력하지 마세요.
curl --fail-with-body \
'https://openapi.letsur.ai/v1/usage?month=2026-08' \
--write-out '\nHTTP %{http_code}\n' \
-H "Authorization: Bearer $LETSUR_MANAGEMENT_KEY"응답 본문 아래 줄이 HTTP 200이고 본문의 periodStart, periodEnd 필드가 조회하려던 기간을 가리키면 조회에 성공한 것입니다. 월별 요청 수와 USD 비용, 모델별, 키별 항목을 읽는 방법은 월별 사용량 조회에서 확인하세요.
현재 보유 유닛과 초과 사용, 차단 상태를 확인하려면 같은 인증 형식으로 유닛 잔액 조회를 요청합니다.
관리 API 키 재발급과 접근 회수
관리 API는 키를 복사한 사람의 현재 역할과 별개로, 요청에 포함된 키로 스페이스를 인증합니다. 키를 복사한 Admin이 Member로 바뀌거나 스페이스에서 제거돼도 이미 복사한 키가 자동으로 무효화되지는 않습니다.
구성원이 관리 API로 더 이상 조회하지 못하게 하려면 그 구성원이 관리 API 키를 보유했을 가능성부터 확인합니다. 복사 여부를 확인하지 못했다면 보유하지 않았다고 판단하지 마세요. 보유했을 가능성을 배제할 수 없다면 남는 Admin이 키를 재발급합니다. 그 구성원이 아직 Admin이면 Member로 변경하거나 스페이스에서 제거한 뒤 재발급하세요. 그 구성원에게 Admin 역할이 남아 있으면 재발급된 새 키도 복사할 수 있습니다.
두 키를 함께 쓸 수 있는 전환 기간은 없습니다. 아래 어느 절차를 따르든 재발급 직후, 계속 사용할 모든 서버와 자동화의 키 값을 새 키로 교체하세요.
재발급에 실패하거나 결과가 불분명하면 이전 키의 접근 회수가 끝났다고 판단하지 마세요. 현재 스페이스의 Admin이 플랫폼 내 문의 기능에 스페이스 이름, 재발급 시각과 오류 내용을 남겨 확인을 요청합니다. 키 값은 보내지 않습니다.
정기 교체나 관리자 변경을 미리 준비할 때
- 현재 스페이스의 Admin이 키를 사용하는 서버와 자동화를 확인하고 전환할 설정을 준비합니다.
- 접근을 회수할 대상이 아직 Admin이면 먼저 역할을 바꾸거나 스페이스에서 제거합니다.
- 재발급한 뒤 계속 사용할 서버와 자동화에 새 키를 즉시 설정합니다.
키 노출 등으로 지금 접근을 회수할 때
- 접근을 회수할 대상이 아직 Admin이면 먼저 역할을 바꾸거나 스페이스에서 제거합니다.
- 사용처 전환을 기다리지 말고 즉시 재발급해 이전 키를 무효화합니다.
- 계속 사용할 서버와 자동화에 설정된 키 값을 새 키로 교체합니다.
안전하게 보관하기
관리 API 키는 서버의 비밀 변수 또는 환경 변수에 저장합니다. 예시의 mk_...는 자리 표시자입니다. 실제 키를 문서나 이슈에 붙여 넣지 않습니다.
오류와 복구
조회가 실패하면 다음을 먼저 확인합니다.
- 호출 주소가 AI 게이트웨이 기본 URL이 아닌
https://openapi.letsur.ai/v1인지 확인합니다. Bearer뒤에 관리 API 키를 지정했는지 확인합니다.- 키를 재발급했다면 이전 키를 사용하는 연동이 없는지 함께 확인합니다.
확인 후에도 조회가 실패하면 플랫폼 내 문의 기능에 스페이스 이름, 발생 시각, 요청 경로, HTTP 상태와 응답의 오류 내용을 남기세요. 관리 API 키와 전체 인증 헤더는 보내지 마세요.