인증 및 멱등성

GET /pricing, GET /openapi.json, GET /openapi.yaml을 제외한 모든 요청에 Authorization: Bearer <credential>을 보내세요. 쿼리 매개변수나 다른 헤더에 담긴 인증 정보는 무시됩니다.

인증 정보는 Bearer 인증을 사용하며, DPoP에 바인딩된 인증 정보는 지원하지 않습니다.

• API 키는 sk_live_로 시작합니다. 설정 → 개발자에서 만들 수 있으며, 키는 한 번만 표시됩니다. 서버에 보관하고 브라우저나 모바일 앱에 포함하지 마세요. 키가 만료되기 7일 전에 이메일로 안내합니다.
• OAuth 액세스 토큰은 sf_at_로 시작합니다. 클라이언트를 승인하면 MCP 클라이언트에 발급됩니다. 설정 → 개발자 → 연결된 앱에서 클라이언트 연결을 해제할 수 있습니다.
• 인증 정보가 없거나 유효하지 않거나 만료 또는 취소되었으면 401 UNAUTHORIZED를 반환합니다. API를 사용할 수 없는 계정(예: 삭제 중인 계정)에는 401 ACCOUNT_UNAVAILABLE을 반환합니다.
• 키를 취소하면 해당 키를 사용하는 새 요청이 중단됩니다. 이미 생성된 작업은 계속 실행되며, 같은 계정의 다른 인증 정보로 조회할 수 있습니다.

인증 정보의 범위를 벗어난 요청은 403 SCOPE_DENIED를 반환합니다. 애플리케이션과 환경마다 별도 키를 사용하면 다른 키에 영향을 주지 않고 하나만 취소할 수 있습니다.

• 모든 생성 요청(POST /images/*, /charts/*, /flowcharts/*)에는 출력 가능한 ASCII 문자 1–255자로 구성된 Idempotency-Key 헤더가 필요합니다. 요청마다 임의의 UUID를 사용하는 것이 가장 간단합니다. POST /files 업로드에도 지정할 수 있습니다(파일 참조).
• 같은 키와 같은 본문으로 보내면 같은 작업을 반환하며 크레딧을 다시 예약하지 않습니다. 그래프 업로드에서는 데이터 파일의 바이트도 본문의 일부입니다.
• 같은 키로 다른 본문을 보내면 409 IDEMPOTENCY_CONFLICT를 반환합니다. 같은 키의 동시 요청이 작업 두 개를 생성하지는 않습니다. 각 요청은 같은 작업을 반환하거나, 첫 번째 요청을 접수하는 동안 Retry-After: 1이 포함된 409 IDEMPOTENCY_IN_PROGRESS를 반환합니다.
• 시간 초과, 네트워크 오류, 429 또는 503 후에는 같은 키로 재시도하세요. 작업이 중복 생성되지 않도록 보장하는 유일한 방법입니다.
• 작업이 생성된 뒤에는 재시도 가능한 오류(429, 503, 409 IDEMPOTENCY_IN_PROGRESS) 또는 500 INTERNAL_ERROR에 details.job_id가 포함됩니다. 같은 키로 재시도하거나 GET /jobs/{job_id}를 폴링하세요. 새 키로 바꾸면 두 번째 작업이 생성되고 과금됩니다. 접수했지만 다시 조회할 수 없는 작업은 queued 상태와 202로 응답합니다.
• 거부된 요청(예: 402 INSUFFICIENT_CREDITS)은 해당 키에 응답을 유지합니다. 충전하거나 업그레이드한 후에는 새 키로 다시 보내세요.

• MCP 클라이언트는 PKCE를 사용하는 OAuth 2.1을 이용합니다. 액세스 토큰(sf_at_…)의 유효 기간은 1시간입니다. offline_access 범위를 요청한 클라이언트에는 30일간 유효한 갱신 토큰(sf_rt_…)도 발급되므로, 연결을 해제할 때까지 연결을 유지할 수 있습니다. offline_access가 없으면 액세스 토큰 만료 시 다시 로그인해야 합니다.
• 갱신 토큰은 갱신할 때마다 새 토큰으로 교체됩니다. 이미 사용한 갱신 토큰을 제시하면 재사용으로 간주되어 그 토큰으로 발급된 토큰이 취소되며, 클라이언트는 다시 로그인해야 합니다.
• 동적 클라이언트 등록 본문은 최대 16 KB이며, 각 필드 길이와 리디렉션 URI 개수에도 제한이 있습니다. 토큰 엔드포인트 인증 방식은 PKCE를 사용하는 공개 클라이언트의 none 또는 client_secret_basic입니다.
• 등록되었지만 한 번도 승인되지 않은 클라이언트는 24시간 후 삭제됩니다.
• prompt=login 또는 max_age가 포함된 인가 요청은 새 로그인을 요구합니다. 이미 로그인한 경우 SciFig는 확인을 받은 뒤 로그아웃과 재로그인을 진행합니다.
• OAuth 인증 정보의 호출 제한은 클라이언트와 계정별로 집계되므로, 같은 어시스턴트의 다른 사용자가 내 한도를 소모하지 않습니다.

모든 응답에 X-Request-Id가 포함되며 오류 본문에도 error.request_id로 표시됩니다. 다른 정보를 노출하지 않고 로그에서 요청을 식별할 수 있으므로, 로그에 기록하거나 지원팀에 전달해도 안전합니다.