인증과 신원

endue OS 의 공개 API 는 둘 중 하나로 인증해요 — endue 계정의 사용자 JWT, 또는 Station API 키. 에이전트와 브라우저 이벤트 구독에는 따로 쓰는 토큰이 있어요.

무엇	모양	어디에	누가
사용자 JWT	Keycloak RS256 액세스 토큰	Authorization: Bearer …	사람, 그 사람의 프로그램
Station API 키	osk_ + 64 hex	Authorization: Bearer osk_… 또는 X-API-Key: osk_…	서버·CI
연결 토큰	osat_{agent_id}_{hex 64}	소켓 주소의 ?token=	에이전트
이벤트 입장권	ostk_ + 64 hex	?ticket=	브라우저 (EventSource·WebSocket 은 헤더를 못 실어요)

사용자 JWT — 하나의 endue 계정

게이트웨이는 endue 셀의 신원 공급자(Keycloak)의 공개 키로 토큰을 검증해요. endue AI 와 같은 계정이에요 (endue AI 와의 관계). 로컬 스택에서는 가짜 신원 공급자가 아무 이름으로 토큰을 줘요:

curl -s -X POST "http://127.0.0.1:5173/idp/token?sub=alice&ttl=3600" | jq -r .access_token

로컬 스택은 개발망 Keycloak(https://id-dev.endue.ai/realms/endue, 클라이언트 endue-os — Authorization Code + PKCE)이 발급한 토큰도 받아요. 그래서 개발망 endue 계정으로도 로그인할 수 있고, 위의 테스트 로그인은 그대로 있어요. 로그인한 계정은 GET /me 로 봐요.

Station API 키

키는 자기 Station 안에서만 통해요. 키가 자기 권한을 넓히지 못하도록, 아래 일은 사용자 JWT 로만 할 수 있어요 — 키로 부르면 403 FORBIDDEN.

• Station 만들기·지우기, API 키 만들기
• virtual Device 만들기·크기 바꾸기·지우기 (비용을 만드는 일)
• 내 정보·프로젝트·빌링·감사 로그 (/me, /projects/*, /billing/*, /audit-logs)

actual Device 등록, virtual Device 시작·정지·재시작, 앱 저장·실행, 명령은 키로도 돼요. 키로 한 일도 그 Station 주인의 계정 크레딧을 써요.

curl -s -X POST $OS/api/v1/stations/$STN/api-keys \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"name":"ci"}' | jq -r .data.secret   # osk_… — 이 응답에서만 보여요

비밀값은 만들 때 한 번만 보여요. 서버에는 해시만 남아요. 폐기한 키는 게이트웨이가 최대 60초 기억할 수 있어요.

권한 모델

• Station 안(기기·명령·Dock·앱)의 인가는 “소유자만” 이에요. 남의 것을 가리키면 403 이 아니라 404 예요 — 있는지조차 알리지 않아요.
• API 키는 자기 Station 밖의 것에 404 예요.
• 프로젝트도 만든 사람만 다뤄요. 남의 프로젝트는 404 PROJECT_NOT_FOUND 예요. 팀·역할은 아직 없어요 — 다른 사용자와 함께 쓰는 것은 예정이에요. 자세한 것은 프로젝트.
• 쓰기 요청(POST·PUT·PATCH·DELETE)은 모두 내 계정의 감사 로그에 남아요 — 사용자인지 API 키인지, 어느 프로젝트·Station 인지도 함께요.

응답 모양

성공은 { data, meta }, 오류는 { error: { code, message, details, suggest }, meta } 예요. 모든 응답에 X-Request-Id 가 붙어요. 오류 코드는 오류 코드 에 있어요.