시작하기

인증

모든 Agent API 요청은 에이전트 키를 Bearer 토큰으로 전달해 인증합니다.

Bearer 토큰 전달

발급받은 에이전트 키(wtr_ak_로 시작)를 HTTP Authorization 헤더에 Bearer 스킴으로 담아 보냅니다.

Authorization 헤더

Authorization: Bearer wtr_ak_xxxxxxxxxxxxxxxxxxxxxxxx

요청 예시

curl -X GET 'https://api.weighter.shop/agent/v1/station' \
  -H 'Authorization: Bearer wtr_ak_xxxxxxxxxxxxxxxxxxxxxxxx'

키를 클라이언트에 노출하지 마세요

에이전트 키는 서버·백엔드 환경에서만 사용하세요. 브라우저·모바일 앱 등 사용자에게 배포되는 코드나 저장소, 로그에 키를 포함하면 안 됩니다.

각 키에는 허용된 작업 범위를 나타내는 스코프가 부여됩니다. 엔드포인트별 필요한 스코프는 API 레퍼런스의 각 엔드포인트에 표시됩니다. 스코프가 부족하면 403 AGENT_003이 반환됩니다.

인증·인가 실패는 표준 오류 봉투로 반환됩니다. HTTP 상태 코드와 error.code를 함께 확인하세요.

오류 응답 예시

{
  "success": false,
  "error": {
    "code": "AGENT_003",
    "message": "요청을 처리할 수 없습니다.",
    "details": null
  }
}

HTTP	코드	의미	대응
401	AGENT_001	유효하지 않은 키	키 문자열과 Authorization 헤더 형식을 확인하세요.
401	AGENT_002	폐기되었거나 만료된 키	소장 콘솔에서 키 상태를 확인하고 필요하면 재발급하세요.
403	AGENT_003	스코프 부족	해당 엔드포인트에 필요한 스코프로 새 키를 발급하세요.
429	AGENT_004	레이트 리밋 초과 (분당 60회)	잠시 대기 후 재시도하세요. 자세한 내용은 레이트 리밋 문서를 참고하세요.

전체 에러 코드 목록은 에러 코드, 요청 한도는 레이트 리밋 문서를 참고하세요.