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일, 영구
키 폐기
더 이상 사용하지 않는 키는 즉시 폐기하세요:
- Open API 페이지에서 키 목록 확인
- 해당 키의 폐기 버튼 클릭
- 확인 모달에서 폐기 선택
API 키는 폐기완료 직후 모든 사용이 중지되오니 폐기 전 관련 키와 연결된 애플리케이션이 있는지 확인하시고 새로운 키를 발급받아 적용하세요.
키 타입
API 키는 용도에 따라 두 가지 타입으로 발급되며, 접근 가능한 엔드포인트가 분리됩니다.
| 타입 | 접두사 | 용도 | 접근 가능 | 차단 |
|---|
| Client SDK | osk_ | iOS/Android, 웹 등의 클라이언트 | persona, chat/, events, data | chat/completions |
| REST API | osr_ | 서버 간 통합 | chat/completions | persona, chat/, events, data |
GET /v1/models는 공통 엔드포인트로, 키 타입에 따라 반환되는 모델이 달라집니다.
테넌트 Open API 페이지에서 발급 시 탭으로 타입을 선택합니다.
잘못된 키 타입으로 엔드포인트에 접근하면 403 Forbidden이 반환됩니다.
스코프 (Scopes)
키 타입에 따라 할당되는 스코프가 다릅니다.
Client SDK (osk_)
| 스코프 | 접근 가능 엔드포인트 |
|---|
persona | /v1/persona/** |
chat | /v1/chat/{persona_id}/** |
data_ingest | /v1/data/events |
REST API (osr_)
| 스코프 | 접근 가능 엔드포인트 |
|---|
chat | /v1/chat/completions |
analytics | /v1/usage |
| 엔드포인트 | 설명 |
|---|
/v1/models | 키 타입에 따라 사용 가능한 모델 반환 |
에러 응답
| HTTP 코드 | 원인 |
|---|
| 401 | API 키 누락, 유효하지 않은 키, 만료된 키 |
| 403 | Open API 비활성화 테넌트, 스코프 부족 |
{
"success": false,
"message": "Invalid or expired API key"
}
보안 권장사항
- API 키를 소스 코드에 직접 포함하지 마세요
- 환경 변수 또는 시크릿 매니저를 사용하세요
- iOS 앱의 경우 Keychain에 저장하세요
- 서버 측에서는 환경 변수로 관리하세요
- 불필요한 키는 즉시 폐기하세요
