# 인증 및 멱등성

모든 SciFig API 호출에 사용하는 인증 정보, 범위, Idempotency-Key 및 요청 ID.

출처: https://scifig.ai/ko/docs/api/authentication

## Bearer 인증

`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`을 반환합니다.
- 키를 취소하면 해당 키를 사용하는 새 요청이 중단됩니다. 이미 생성된 작업은 계속 실행되며, 같은 계정의 다른 인증 정보로 조회할 수 있습니다.

## 범위

| 범위 | 부여하는 권한 | API 키 유형 |
| --- | --- | --- |
| figures:read | `GET /jobs`, `GET /jobs/{id}`, `GET /files/{file_id}`, `GET /credits` | 읽기 전용 키. 만료되지 않도록 설정 가능 |
| figures:generate | `figures:read`의 모든 권한과 모든 `POST` 엔드포인트 | 생성용 키. 30일, 90일 또는 1년 후 만료. 활성 구독 또는 0보다 큰 크레딧 팩 잔액 필요 |

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

## 멱등성

- 모든 생성 요청(`POST /images/*`, `/charts/*`, `/flowcharts/*`)에는 출력 가능한 ASCII 문자 1–255자로 구성된 `Idempotency-Key` 헤더가 필요합니다. 요청마다 임의의 UUID를 사용하는 것이 가장 간단합니다. `POST /files` 업로드에도 지정할 수 있습니다([파일](/ko/docs/api/files#upload) 참조).
- 같은 키와 같은 본문으로 보내면 같은 작업을 반환하며 크레딧을 다시 예약하지 않습니다. 그래프 업로드에서는 데이터 파일의 바이트도 본문의 일부입니다.
- 같은 키로 다른 본문을 보내면 `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`)은 해당 키에 응답을 유지합니다. 충전하거나 업그레이드한 후에는 새 키로 다시 보내세요.

## OAuth 클라이언트

- 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 인증 정보의 호출 제한은 클라이언트와 계정별로 집계되므로, 같은 어시스턴트의 다른 사용자가 내 한도를 소모하지 않습니다.

## 요청 ID

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