워크스페이스와 테넌시¶
워크스페이스는 회원·API key·시나리오·대화를 격리하는 테넌트 경계입니다. JWT 요청은
X-Workspace-Id 헤더로 대상을 고르고, API key 요청은 키에 귀속된 워크스페이스가 자동으로
대상이 됩니다.
컨텍스트 해석¶
회원 JWT¶
X-Workspace-Id가 있으면 UUID 형식을 확인합니다.- JWT subject의 회원이 해당 워크스페이스의
ACTIVE멤버인지 조회합니다. - 비멤버는 403, 잘못된 UUID는 400입니다.
- 성공하면 요청 수명 동안
TenantContext와 Hibernate tenant filter를 활성화합니다.
헤더가 없는 JWT 요청 자체는 필터에서 통과합니다. 테넌트가 필수인 서비스가
TenantContext.require()를 호출할 때 400으로 거절하는 구조입니다.
워크스페이스 API key¶
- 헤더가 없어도 키의 귀속 워크스페이스를 컨텍스트로 설정합니다.
- 헤더를 함께 보내면 키의 워크스페이스와 같아야 합니다.
- 다른 워크스페이스 ID를 지정하면 403입니다.
- 키는
SCOPE_WORKSPACE_READ만 가지며 회원 JWT 역할을 대신하지 않습니다.
헤더가 필요한 작업¶
- 일반 시나리오 생성·목록·상세와 이력 조회
- API key 발급·목록·폐기
- client-secret 발급
- 사용자 그룹 생성·조회·구성원 관리
- JWT로 대화 메시지 음성을 프록시 조회하는 작업
- 사용자 그룹 대화 통계
워크스페이스 생성과 내 소속 워크스페이스 목록은 부트스트랩 경로이므로 헤더가 필요 없습니다. 전역 시나리오 카탈로그와 음색 프리셋, 회원 개인 설정도 워크스페이스 비종속입니다.
역할 규칙¶
- 워크스페이스 생성자: 소유자이자
OWNER/ACTIVE멤버로 자동 등록 - API key 발급·목록·폐기:
OWNER만 가능 - client-secret 발급: 해당 워크스페이스의 모든
ACTIVE멤버 가능 - 사용자 그룹 관리:
OWNER만 가능 - 사용자 그룹 통계: JWT 회원은
OWNER만, 읽기 scope API key는 귀속 워크스페이스에서 가능 - 초대, 역할 변경, 소유권 위임 API: 현재 미구현
경계별 조회 규칙¶
일반 시나리오와 이력은 workspace_id를 명시적으로 요구합니다. API key 인증은 키의 귀속
워크스페이스로 강제되므로 헤더가 없어도 교차 테넌트 조회가 되지 않습니다.
대화 조회의 현재 동작
대화 음성 프록시는 JWT 요청에 X-Workspace-Id를 강제하지만, 대화 목록·상세·세션 상세는
기준 커밋에서 JWT 헤더가 없을 때 TenantContext 없이 진행될 수 있습니다. 이를 모든 대화
조회가 헤더를 강제한다고 일반화하면 안 됩니다. 호출자는 항상 헤더를 보내고, 운영 보안
검토에서는 이 구현 차이를 별도 위험으로 다뤄야 합니다.
API key와 client-secret 차이는 API key와 client-secret, 전체 엔드포인트 적용 범위는 REST API 참조를 참고하세요.