Skip to main content

API Access Key Core

multi-saas-kit는 API 인증을 프로젝트별 임시 구현이 아니라 공용 Core 보안 기능으로 다룹니다.

현재 이 구조는 apis.how, speech-service, llm.apis.how 연동에서 먼저 적용되어 있고, 다른 API 서비스도 같은 방식을 따르는 것이 권장됩니다.

왜 Core인가​

다음 요구가 반복되기 때문입니다.

  • 평문 API key 저장 금지
  • 서비스별 ability 제어
  • rate limit / timeout / 만료 / network restriction
  • Laravel, Go, Python 서비스의 공통 검증
  • 사용량과 비용 추적

이 기능을 서비스마다 따로 만들면 정책이 쉽게 어긋납니다.

핵심 구조​

Browser / App / Server
        │
        │ Bearer access key
        ▼
speech.apis.how / tts / stt / llm
        │
        ├─ auth middleware
        ├─ short cache
        └─ introspection
                │
                ▼
API Access Key Authority (Laravel Core)
        │
        ├─ public_key_id + secret_hash
        ├─ policy evaluation
        ├─ revoke / rotate
        └─ usage / audit

저장 원칙​

  • DB에는 plain token을 저장하지 않습니다.
  • 토큰은 public_key_id + secret 구조로 발급합니다.
  • UI에서는 발급 직후 1회만 plain token을 보여줍니다.
  • 이후에는 Edit, Rotate, Revoke 중심으로 운영합니다.

정책으로 제어하는 항목​

  • service
  • abilities
  • allowed_routes
  • allowed_aliases
  • allowed_ip_cidrs
  • allowed_origins
  • allowed_domains
  • allow_rest
  • allow_websocket
  • rate_limit
  • max_timeout_ms
  • max_concurrent_requests
  • expires_at

키 타입​

타입용도권장 제약
internal_service서비스 간 내부 호출IP 제한, 높은 신뢰
server_secret프로젝트 백엔드장기 키, IP 제한 권장
browser_restricted브라우저 직접 호출origin/domain 제한, 낮은 권한
session_ephemeralWebSocket/실시간 세션짧은 TTL, 세션 전용

speech-service에 어떻게 적용되나​

  • 내부 LLM_API_KEY
    • speech-service -> llm.apis.how 호출용 internal key
  • 외부 Speech API Token
    • 사용자가 speech.apis.how를 호출할 때 쓰는 access key
  • 검증 방식
    • speech-service가 중앙 introspection endpoint를 조회
    • 결과를 짧게 cache
    • 요청별 route / IP / origin / domain / websocket 제약을 다시 평가

사용량과 비용​

공용 access key 구조는 인증만 담당하지 않습니다.

  • 어떤 토큰이 어떤 서비스를 호출했는지
  • 어떤 endpoint를 얼마나 썼는지
  • estimated cost와 actual cost를 어떻게 비교할지

이 정보도 함께 남길 수 있게 설계되어 있습니다.

현재 speech-service는 api_usage_logs에 사용량을 남기고, LiteLLM spend 로그를 이용해 실제 LLM 비용을 backfill할 수 있는 구조를 사용합니다.

운영 권장사항​

  • 브라우저에는 장기 키보다 session_ephemeral을 우선 고려하세요.
  • server token에는 allowed_ip_cidrs를 우선 적용하세요.
  • browser token에는 allowed_origins, allowed_domains를 함께 쓰세요.
  • high-cost feature는 별도 ability로 분리하세요.
  • plain token은 발급 직후 안전한 장소에만 보관하세요.

함께 보면 좋은 문서​