인증
- Authorization: ApiKey
- API 키는 POST /api/v1/auth/token 의 Authorization 헤더에만 전송합니다. JSON, URL, 쿼리 매개변수에 넣지 마세요.
- Authorization: Bearer
- 리소스 요청에는 반환된 토큰을 사용하고 expires_at 에 따라 갱신하세요. expires_in 의 단위는 초입니다.
왜 먼저 토큰을 받아야 하나요?
API 키로 토큰을 발급받습니다. 토큰은 15분 동안 유효하며 여러 요청에 사용할 수 있습니다. 리소스에는 Authorization: Bearer 헤더로 토큰만 전송합니다.
일반 요청에는 API 키가 포함되지 않습니다. 토큰만 유출되면 유효 기간이 끝날 때까지만 접근할 수 있습니다. 하지만 API 키를 도난당하면 새 토큰이 계속 발급될 수 있습니다.
토큰은 얼마나 유효한가요?
- expires_in
- 발급 시점부터 900초, 즉 15분입니다. 요청을 보내도 유효 기간은 연장되지 않습니다.
- expires_at
- UTC 기준 만료 시각입니다. 현재 접근 제한에 따라 그 전에 토큰이 차단될 수 있습니다.
새 토큰은 언제 받아야 하나요?
같은 토큰을 여러 요청에 재사용하고 expires_at 이전에 새 토큰을 받으세요. 작업마다 토큰을 받을 필요는 없습니다. 새 토큰을 받으려면 API 키를 사용하세요.
접근 거부 및 재시도
- 401
- 401이 항상 토큰 만료를 뜻하지는 않습니다. 만료되었다면 새 토큰을 받고 읽기 요청을 최대 한 번만 재시도하세요. 토큰 발급이 401을 반환하면 키를 확인하고 자동 시도를 중지하세요.
- 403
- 403이면 권한, IP 제한 및 요금제를 확인하세요. 새 토큰을 받아도 취소된 접근 권한이 복구되지는 않습니다.
IP 제한
- 액세스 토큰으로도 키의 현재 권한, 스토어 이용 권한, 폐기 상태 또는 IP 제한을 우회할 수 없습니다.
- 필요한 경우 키 사용을 연동의 출발지 주소로 제한하세요.
- 관리자가 목록을 편집할 수 있으며 주소는 최대 32개까지 허용됩니다.
키 관리
- API 키 관리 권한은 연동의 리소스 권한과 별개입니다.
- 그룹에 키 조회, 생성, 편집, 삭제 관리 권한을 부여할 수 있는 주체는 owner 뿐입니다.
- 권한이 있는 그룹 구성원은 그룹에 부여된 작업만 수행할 수 있습니다.
요청 속도 제한
Engine ≥ 4.143.0. 각 토큰 응답에는 발급 당시 스토어 정책의 data.rate_limits가 포함됩니다. 모든 키가 이 한도를 공유하며 새 토큰을 받아도 초기화되지 않습니다. 요금제 변경은 토큰 만료 전에 적용될 수 있습니다.
- read_per_minute
- 분당 읽기 요청 수입니다.
- write_per_minute
- 분당 쓰기 요청 수입니다. 이 값은 쓰기 권한을 부여하지 않습니다.
- auth_per_minute
- 인증 실패를 포함한 분당 토큰 요청 수입니다.