인증과 API 키
/v1의 모든 요청은 API 키로 인증합니다.
curl -s "https://api.upserve.app/v1/deployments" \
-H "Authorization: Bearer $UPSERVE_API_KEY"키 모양은 up_로 시작하는 문자열입니다. 키가 없거나 형식이 틀리거나 폐기·만료된 경우 401 INVALID_API_KEY입니다.
키는 한 번만 보입니다
- 키 원문은 생성할 때와 회전할 때의 응답에서 한 번만 보입니다. 서버는 키의 단방향 해시만 저장하므로 다시 보여 줄 수 없습니다.
- 잃어버렸다면 새 키를 만들거나 회전하세요.
- 환경변수나 비밀 저장소에 보관하고, 코드·로그·오류 보고·브라우저·모바일 앱에 넣지 마세요.
- 키는 Project에 속합니다. 키 관리(생성, 회전, 폐기)는 조직 OWNER가 로그인한 관리 화면 또는 관리 API로만 하며, 실행용 API 키로는 할 수 없습니다.
- 키를 발급한 사람이 조직 OWNER 권한을 잃으면 그 키는
401 INVALID_API_KEY가 됩니다.
scope
키마다 허용 scope를 고릅니다. scope가 없는 작업은 403 INSUFFICIENT_SCOPE입니다.
| scope | 허용하는 작업 |
|---|---|
deployments:read | Deployment 목록과 상세 조회 |
sessions:read | Session 조회, Item 조회 |
sessions:write | Session 생성, close, 삭제 |
turns:read | Turn 목록과 상세 상태 조회 |
turns:write | Turn 생성 (Session 생성의 첫 Turn 포함) |
turns:cancel | Turn 취소 |
events:read | Session과 Run의 이벤트(SSE) 조회 |
usage:read | 사용량 조회 |
files:write | 입력 파일 업로드 (Session 파일 포함) |
artifacts:read | Artifact 상세 조회와 다운로드 |
workflows:read | 워크플로 상세 조회 |
workflows:run | Run 접수 |
runs:read | Run 상태와 결과 조회 |
runs:cancel | Run 취소 |
runs:delete | Run 삭제 |
actions:resolve | 호출자가 풀 수 있는 질문(RequiredAction) 해소 |
actions:approve | 고객 서비스에서 받은 사람 승인·거절 제출(명시적 별도 위임) |
works:read | 조직 업무 준비 조회와 목록 |
works:write | 조직 업무 접수, 명세 수정, 준비 질문 답 |
works:approve | 고객 서비스에서 받은 사람의 범위 확인 답 제출(명시적 별도 위임) |
한 요청이 여러 scope를 요구할 수 있습니다. 예를 들어 Session 생성은 sessions:write와 turns:write가, Turn 결과 조회는 turns:read와 sessions:read가 필요합니다. 필요한 최소 scope만 부여하세요.
Deployment와 워크플로 허용 목록
키는 scope와 별개로 호출할 수 있는 Deployment와 워크플로 목록을 가집니다.
- 키에 없는 Deployment나 워크플로는 존재 여부를 알려 주지 않도록
404 NOT_FOUND로 응답합니다. - 실제 권한은 키 scope, Project와 키의 허용 목록, 발행 시 고정된 capability의 교집합입니다. scope만으로 권한이 늘어나지 않습니다.
- 용도마다 키를 나누고, 키마다 필요한 Deployment만 허용하세요.
- works scope가 하나 이상 있고 나머지가
usage:read뿐인 키는 Deployment를 실행하지 않으므로 Deployment 없이 만들 수 있습니다. 그 밖의 scope를 섞은 키는 Deployment가 하나 이상 필요합니다. 자세한 내용은 조직 업무 만들기를 보세요.
회전
키를 교체할 때는 회전을 씁니다. 회전하면 같은 이름, scope, 허용 목록의 새 키가 만들어지고, 새 키 원문이 응답에 한 번 나옵니다.
- 회전 때 겹침 시간(
overlap_seconds, 0~86,400초)을 명시적으로 고릅니다. 기본값 0은 이전 키를 즉시 폐기합니다. - 겹침 시간을 주면 이전 키는 그 시간이 지나면 만료되고, 그동안 두 키가 모두 동작합니다. 호출 측이 새 키로 옮길 시간을 확보하는 용도입니다.
- 이미 폐기·만료됐거나 이미 회전한 키를 다시 회전하면
409 KEY_NOT_ROTATABLE입니다. 새 키를 만드세요. - 멱등 receipt는 Project 범위로 유지되므로 회전해도 같은
Idempotency-Key재전송이 이어집니다.
폐기
- 폐기는 커밋 직후 새 요청과 새로운 외부 효과 시작을 즉시 막습니다. 이후 요청은
401 INVALID_API_KEY입니다. - 이미 접수된 미완료 Turn과 Run은 취소 요청으로 전환됩니다. 이미 끝난 외부 효과는 되돌리지 않으며, 진행 중이던 모델 호출까지 즉시 멈춘다고 보장하지 않습니다.
- 열려 있는 SSE 연결도 주기적인 재검증에서 닫힙니다.
- Project 자체를 폐기하면 그 Project의 키도 모두 못 씁니다.
만료
키에는 호출자가 직접 정하는 수명(만료일)이 없습니다. 키가 만료되는 경우는 두 가지입니다.
- 겹침 시간을 준 회전 이후 이전 키가 정해진 시각에 만료될 때
- 소유자가 폐기할 때
정기적으로 회전해 키 수명을 짧게 유지하세요.
호출 속도 한도
키와 Project, Deployment 단위로 호출 속도를 제한합니다. 초과하면 429 RATE_LIMITED와 Retry-After가 옵니다. 수치는 한도와 데이터를 보세요.