인증

이 문서는 영문 원고를 AI로 번역한 내용이라 표현이 어색할 수 있습니다.

Sume Developer API 요청은 워크스페이스 단위 API 키로 인증합니다. API 키는 API Keys 대시보드에서 발급하세요.

API 키 보내기

서버 쪽 환경 변수를 사용하세요.

이어서 Bearer 인증을 보내거나:

API 키 헤더를 보낼 수 있습니다.

현재 API는 두 형태를 모두 받습니다. 연동마다 한 가지를 일관되게 사용하세요. Sume CLI는 기본으로 x-api-key를 쓰고, 설정하면 Bearer 모드도 사용할 수 있습니다.

단, 반드시 하나만 보내세요. Authorization: Bearer와 x-api-key를 함께 실은 요청은 401 unauthorized와 Send only one API key credential. 메시지로 거부됩니다. 어느 쪽이 이기는 것도 아니고, 뒤쪽이 앞쪽을 조용히 가려 버리지도 않습니다. 이미 x-api-key를 보내는 클라이언트 위에 게이트웨이나 fetch 래퍼가 자체 Authorization 헤더를 얹을 때 자주 발생합니다. 존재하지 않는 우선순위 규칙에 기대지 말고 둘 중 하나를 제거하세요.

범위(Scope)

Sume는 키에서 워크스페이스, 소유자, API 키 메타데이터를 해석합니다.

공개 API 요청 본문에 workspace_id, owner_user_id, user_id를 넣지 마세요.

응답에는 id, name, prefix, scopes, 마지막 사용 시각 같은 키 메타데이터가 노출되지만, 전체 시크릿은 절대 돌아오지 않습니다.

스코프는 키를 만들 때 고정되며, 나중에 추가할 수 없습니다. 어떤 스코프가 생기기 전에 만든 키에는 그 스코프가 없습니다. 특히 Actions API로 Scheduled 실행에 필요한 actions:read와 actions:write는 Actions API 호출 트리거가 출시된 뒤에 만든 키에만 발급됩니다. 이전 키는 모든 Action run 요청에서 403 insufficient_scope를 반환하니, 새 키를 만들고 교체하세요. 같은 함정이 formats:read / formats:write에도 적용됩니다. Formats 이전에 만든 키로 Format을 호출하면 403 insufficient_scope이며, 404 format_not_found가 아닙니다. 기존 키에 스코프를 덧붙이는 API는 없습니다.

서버 프록시 패턴

브라우저와 모바일 클라이언트는 백엔드를 호출해야 합니다. 백엔드가 Sume API 키를 붙이세요.

Sume로 전달하기 전에 사용자 입력을 검증하고, 자체 인가를 적용하세요.

키 교체(Rotation)

대체 키를 만들고 서버에 배포한 뒤 GET /v1/me로 확인한 다음, 대시보드에서 이전 키를 폐기하세요. 키가 로그나 채팅 기록에 노출됐다면 반드시 교체하세요.

안전 규칙

API 키는 신뢰할 수 있는 서버, CI 시크릿 저장소, 로컬 개발 머신에만 두세요.
프론트엔드 JavaScript, 모바일 앱, 지원 티켓, 스크린샷에 API 키를 넣지 마세요.
서명된 업로드·다운로드 URL은 임시 시크릿으로 취급하세요.
키가 노출되면 대시보드에서 교체하세요.
Agent에는 먼저 읽기 전용 명령을 주고, 쓰기나 유료 생성 명령 전에 명시적 확인을 요구하세요.

요청 한도

모든 API 키에는 /v1 전체에 적용되는 분당 요청 예산이 있으며, 키가 속한 워크스페이스의 구독 플랜에 따라 결정됩니다. 읽기와 쓰기는 예산이 분리되어 있으므로, 촘촘한 상태 폴링 루프가 본인의 제출 요청을 429로 만들지 않습니다.

플랜	분당 쓰기	분당 읽기
Free	120	4800
Pro	300	12000
Startup	600	24000
Scale	1200	48000
Enterprise	영업팀 문의	영업팀 문의

읽기는 모든 GET·HEAD입니다 — status_url·events_url·result_url 폴링, Format이나 run 목록 조회. 여기에 아무것도 제출하지 않는 두 POST, /v1/generation/admission-preview와 MCP 엔드포인트 자체가 함께 읽기로 계산됩니다. 그 외에는 모두 쓰기입니다 — run 생성, 취소, 업로드. 플랜에 적힌 숫자가 쓰기 숫자이고, 읽기는 그 40배를 별도 버킷으로 받습니다.

이 배수는 run 하나를 지켜보는 사람이 아니라 에이전트를 기준으로 잡은 값입니다. 에이전트 수확은 스무 개 넘는 Job을 동시에 열어 두고 각각을 폴링하기 때문에, 비용이 들지 않는 작업에 분당 수천 건의 읽기가 발생합니다. 그래서 읽기는 의도적으로 싸게 두고, 플랜이 실제로 구매하는 쓰기 예산은 건드리지 않습니다.

Enterprise는 셀프서비스가 아닙니다. 계약된 값이 프로비저닝되기 전까지 Enterprise 키는 위 표의 Scale 행으로 해석됩니다.

MCP 도구 호출은 그 호출이 만드는 run에 대해 쓰기 예산을 한 번만 씁니다. 도구를 실어 나른 JSON-RPC 요청 자체에는 쓰기 예산이 붙지 않으며, MCP로 하는 jobs_status 폴링은 쓰기 예산을 전혀 쓰지 않습니다.

요청 수를 직접 세지 말고 ratelimit-remaining 값을 읽고, retry-after에 맞춰 백오프하세요. 헤더는 이번 요청이 사용한 예산을 가리키며, 429는 error.details.scope(read 또는 write)로 어느 예산인지 알려 줍니다.

요청 한도와 생성 처리량은 다릅니다. 동시에 실행되는 생성 작업 수는 플랜의 동시성 한도가 따로 관리하며 generation_limits 객체로 노출됩니다. 요청 한도를 올려도 생성 동시성은 올라가지 않습니다.

모든 응답에 현재 상태가 함께 옵니다.

헤더	의미
`ratelimit-limit`	현재 창에서 허용되는 요청 수입니다.
`ratelimit-remaining`	현재 창에 남은 요청 수입니다.
`ratelimit-reset`	창이 초기화되기까지 남은 초입니다.
`retry-after`	`429`에서 내려오는, 기다려야 할 초입니다.

인증되지 않은 요청은 클라이언트 IP 단위로 Free 한도가 적용되며, 읽기 버킷은 40배가 아니라 쓰기 한도의 4배로 묶입니다. 에이전트 크기의 읽기 예산은 자기가 만든 Job을 폴링하는 호출자를 위한 것이고, 익명 버킷까지 넓히면 남용 표면만 함께 넓어지기 때문입니다.

읽기 배수는 배포 설정(SUME_COM_API_RATE_LIMIT_READ_MULTIPLIER)이므로 셀프호스팅이나 프리뷰 배포에서는 다를 수 있습니다. 지금 통신하는 배포의 실제 값은 언제나 응답의 ratelimit-limit이 알려 주며, 위 표는 출시된 기본값입니다.

자주 보는 실패

Status	흔한 원인	다음 단계
`401`	키가 없거나, 형식이 잘못됐거나, 폐기된 경우입니다.	헤더를 확인하고 필요하면 새 키를 만드세요.
`403`	키는 유효하지만 요청한 표면에 권한이 없습니다.	워크스페이스 멤버십과 키 스코프를 확인하세요.
`429`	플랜의 분당 요청 한도를 초과했습니다.	`retry-after`에 맞춰 백오프하여 다시 시도하세요.