🔐 API Access Keys

multi-saas-kit의 API 서비스는 공통 API Access Key Core 위에서 동작합니다.

즉 speech.apis.how, tts, stt, llm.apis.how는 서로 다른 서비스여도 비슷한 발급/편집/회수 정책을 공유합니다.

기본 원칙

• 발급 직후에만 plain token을 볼 수 있습니다.
• DB에는 plain token이 아니라 hash만 저장됩니다.
• 이후에는 Edit, Rotate, Revoke 중심으로 운영합니다.
• key는 API 버전 기준이 아니라 소비 주체와 정책 기준으로 발급합니다.

예:

• exam-how-web-prod
• edutech-how-server-prod
• speech-browser-session

키 타입

타입	설명
internal_service	내부 서비스 간 호출
server_secret	프로젝트 서버/워커
browser_restricted	브라우저 직접 호출
session_ephemeral	WebSocket/실시간 세션

제어 가능한 정책

• service scope
• abilities
• allowed routes
• allowed LLM aliases
• rate limit
• request timeout ceiling
• concurrent request limit
• expiry
• IP/CIDR 제한
• allowed origins
• allowed domains
• REST / WebSocket 허용

브라우저용과 서버용을 나누세요

server token

• allowed_ip_cidrs 사용 권장
• 장기 키 가능
• Origins / Domains는 보통 비워도 됨

browser token

• allowed_origins가 핵심
• allowed_domains는 보조 제약
• 낮은 rate limit과 짧은 만료 권장

발급 후 꼭 기억할 점

• plain token은 다시 볼 수 없다고 가정하세요.
• 안전한 secret manager나 운영 vault에 바로 저장하세요.
• 잃어버리면 Rotate 또는 새 token 발급이 맞습니다.

Speech API에 쓰려면

권장 최소 조건:

• ability: conversation:stream
• allow_websocket = true

필요 시 추가:

• allowed_origins
• allowed_domains
• allowed_ip_cidrs
• max_timeout_ms

Platform Admin에서 어디서 관리하나

• Speech API > API Tokens
• TTS API > API Tokens
• STT API > API Tokens
• LLM API > API Tokens 또는 공용 token resource

서비스별 메뉴는 다르지만, 기본 access key 정책은 공통입니다.

Usage와 함께 보세요

API key 운영은 발급만으로 끝나지 않습니다.

• API Management > Usage Dashboard
• Speech API > Usage
• TTS API > Usage
• STT API > Usage

이 페이지에서 서비스별 요청량, 오류, estimated cost, actual cost 반영 상태를 함께 봅니다.

버전별로 키를 만들어야 하나

기본 원칙은 아닙니다.

• key는 소비 주체 기준으로 발급
• 버전은 allowed_routes로 제어

예외적으로 v1과 v2가 장기간 병행되고 정책이 크게 다를 때만 별도 key를 고려합니다.

함께 보면 좋은 문서

• API Access Key Core
• speech.apis.how
• llm.apis.how