API 키 인증
모든 Open API 요청에는 Bearer 토큰 형식의 API 키가 필요합니다.
Authorization: Bearer osk_megamart_a1b2c3d4e5f6g7h8...
API 키 발급
사전 조건
- 테넌트 관리자(admin) 권한 필요
- 어드민에서 해당 테넌트의 Open API가 활성화되어 있어야 함
발급 절차
- 테넌트 페이지에 관리자로 로그인
- 프로필 메뉴에서 Open API 클릭
- 새 API 키 발급 버튼 클릭
- 키 이름과 만료 기간 선택
- 발급된 키를 안전한 곳에 복사
API 키는 발급 시 한 번만 표시됩니다. 이후에는 다시 확인할 수 없으므로 반드시 안전한 곳에 보관하세요.
만료 기간 옵션
| 옵션 | 설명 |
|---|
| 7일 | 테스트/개발용 |
| 14일 | 단기 프로젝트 |
| 30일 | 기본값 |
| 60일 / 90일 | 중기 운영 |
| 180일 / 365일 | 장기 운영 |
| 영구 | 만료 없음 |
키 형식
osk_{tenant_code}_{random_hex_64}
osk_megamart_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6
키 관리
키 폐기
더 이상 사용하지 않는 키는 즉시 폐기하세요:
- Open API 페이지에서 키 목록 확인
- 해당 키의 폐기 버튼 클릭
- 확인 모달에서 폐기 선택
폐기된 키는 즉시 사용할 수 없으며, 복구할 수 없습니다.
키 상태
| 상태 | 설명 |
|---|
| 활성 | 정상 사용 가능 |
| 만료 | 만료일이 지남 (자동) |
| 폐기 | 수동으로 폐기됨 |
스코프 (Scopes)
API 키에는 다음 스코프가 할당됩니다:
| 스코프 | 접근 가능 엔드포인트 |
|---|
chat | /chat/completions, /models |
data_ingest | /data/events |
analytics | /usage |
에러 응답
| HTTP 코드 | 원인 |
|---|
| 401 | API 키 누락, 유효하지 않은 키, 만료된 키 |
| 403 | Open API 비활성화 테넌트, 스코프 부족 |
{
"success": false,
"message": "Invalid or expired API key"
}
보안 권장사항
- API 키를 소스 코드에 직접 포함하지 마세요
- 환경 변수 또는 시크릿 매니저를 사용하세요
- iOS 앱의 경우 Keychain에 저장하세요
- 서버 측에서는 환경 변수로 관리하세요
- 불필요한 키는 즉시 폐기하세요
