개발자

Sume API 키 동작 방식: 스코프, 인증 헤더, 호스트, 교체

Sume API 키는 워크스페이스 단위 시크릿으로, Bearer나 x-api-key 중 하나로만 보냅니다. 스코프는 생성 시 고정되고, 키는 발급된 호스트에서만 동작합니다.

읽는 시간 5분Sume
전체 글

Sume API 키는 API Keys 대시보드에서 만드는 워크스페이스 단위 시크릿입니다. 모든 요청에 Authorization: Bearer나 x-api-key 중 하나로 보내며, 둘을 함께 보내서는 안 됩니다. 스코프는 키를 만들 때 고정되고, 키는 발급된 호스트에서만 동작합니다.

아래 내용은 모두 Sume의 인증과 API 키 문서, 그리고 Format 호출하기 (영문)와 Format API (영문) 개요의 키·호스트 섹션에서 가져왔습니다.

Sume API 키는 어떻게 보내나요?

키는 서버 쪽 환경 변수에 두고, 두 헤더 중 하나로 보내세요. API는 두 헤더를 모두 받지만, 연동마다 한 가지를 일관되게 쓰세요. Sume CLI는 기본으로 x-api-key를 씁니다.

정확히 하나만 보내세요. Authorization: Bearer와 x-api-key를 함께 실은 요청은 401 unauthorized와 Send only one API key credential. 메시지로 거부됩니다. 어느 헤더도 우선하지 않습니다. 이미 x-api-key를 보내는 클라이언트 위에 자체 Authorization 헤더를 덧붙이는 게이트웨이와 fetch 래퍼가 이 규칙에 걸립니다.

curl https://api.sume.com/v1/me \
  -H "Authorization: Bearer $SUME_API_KEY"

# or, never both:
curl https://api.sume.com/v1/me \
  -H "x-api-key: $SUME_API_KEY"

키가 대신 정해 주는 것은 무엇인가요?

Sume는 워크스페이스, 소유자, 키 메타데이터를 키 자체에서 알아냅니다. 공개 API 요청 본문에 workspace_id, owner_user_id, user_id를 넣지 마세요. 응답에는 id, 이름, 접두사, 스코프, 마지막 사용 시각 같은 키 메타데이터가 나오지만, 전체 시크릿은 절대 나오지 않습니다.

대시보드는 키를 만들 때만 전체 시크릿을 보여 주므로, 곧바로 안전한 시크릿 매니저에 저장하세요. 키마다 워크스페이스 요금제로 정해지는 분당 요청 예산도 따로 있습니다. Sume API 오류와 요청 한도를 참고하세요.

키에는 어떤 스코프가 필요한가요?

스코프는 키를 만들 때 고정되며 나중에 추가할 수 없습니다. 어떤 스코프가 생기기 전에 만든 키에는 그 스코프가 없고, 기존 키에 스코프를 덧붙이는 API도 없습니다. 새 키를 만들어 교체하세요.

  • Formats 스코프가 없는 키로 보낸 Format 요청은 모두 403 insufficient_scope로 실패하며, 404 format_not_found가 나오는 일은 없습니다.
  • Actions 스코프가 없는 이전 키는 모든 Action 실행 요청에서 403 insufficient_scope를 반환합니다.
  • 서비스 계정 키로는 Format 실행을 만들 수 없습니다. 403 insufficient_scope와 함께 details.reason이 service_account_format_runs_unsupported인 응답으로 실패합니다.
Format 호출하기 (영문)와 인증 기준 스코프, 2026-09-25 확인.
스코프필요한 작업
formats:readFormat 목록 조회와 읽기, 실행 읽기와 목록 조회, 큐 읽기
formats:write실행 생성, 대량 실행 큐 생성, 실행 취소, 웹훅 재전송
actions:read, actions:writeActions API를 통한 Scheduled 실행(Actions API 호출 트리거가 출시된 뒤에 만든 키에만 발급)

401, 403, 404는 키에 대해 무엇을 알려 주나요?

HTTP 상태로 먼저 분기하고, 그다음 error.code로 분기하세요. 403 workspace_key_required는 팀은 맞지만 키가 틀렸다는 뜻입니다. 팀 Format은 그 팀 워크스페이스에서 만든 키로 호출해야 하고 멤버십만으로는 부족하며, details.workspace_id가 키를 만들 워크스페이스를 알려 줍니다. 이 규칙은 돈의 흐름을 따릅니다. 팀 Format의 실행은 팀 지갑에 청구되고 팀의 생성 동시성에 포함되기 때문입니다.

Format 호출하기 (영문)와 Format API (영문) 개요 기준, 2026-09-25 확인.
HTTP오류 코드발생 조건
401unauthorized키 없음, 형식이 잘못된 키, 자격 증명 두 개 동시 전송, 폐기되었거나 알 수 없는 키, 다른 호스트용 키
403insufficient_scopeformats:read 또는 formats:write가 없는 유효한 키(details.required_scope가 빠진 스코프를 알려 줌), 또는 실행을 만드는 서비스 계정 키
403workspace_key_required팀 워크스페이스 멤버이지만 개인 키를 보낸 경우
404format_not_found알 수 없거나 보관된 Format, 이 키의 워크스페이스 밖에 있는 Format, 또는 멤버가 아닌 팀의 핸들

키는 어느 호스트에서 동작하나요?

프로덕션은 https://api.sume.com입니다. 여기서 실행하면 워크스페이스의 실제 크레딧이 쓰이고, 키는 API 키 대시보드에서 발급합니다. Sume는 연동과 스테이징을 위한 별도의 개발 호스트도 운영하며, 경로, 영수증, 웹훅 전달은 프로덕션과 같습니다. 개발 호스트의 키는 개발 워크스페이스용으로 발급되니 Sume 담당자에게 문의하세요.

  • 키는 발급된 호스트에서만 동작합니다. 다른 호스트는 401 unauthorized로 응답합니다.
  • 두 호스트의 키가 모두 sume_live_… 형태이므로, 환경 변수 이름은 접두사가 아니라 호스트를 기준으로 지으세요.

키는 어떻게 교체하고 안전하게 보관하나요?

대체 키를 만들어 서버에 배포하고 GET /v1/me로 확인한 뒤, 대시보드에서 이전 키를 폐기하세요. 로그나 채팅 기록에 나타난 키는 모두 교체하세요.

  • 키는 신뢰할 수 있는 서버, CI 시크릿 저장소, 로컬 개발 머신에 두세요.
  • 프론트엔드 JavaScript, 모바일 앱, 지원 티켓, 스크린샷에 키를 넣지 마세요. 브라우저와 모바일 클라이언트는 백엔드를 호출해야 하며, 백엔드가 입력을 검증하고 자체 인가를 적용한 뒤 키를 붙입니다.
  • 에이전트에게는 읽기 전용 명령어부터 주고, 쓰기나 유료 생성 명령어 전에는 명시적인 확인을 요구하세요.

출처

관련 글

작성자 Sume