인증

봇이 부르는 API는 개발자 토큰으로 인증해요. 토큰은 봇이 아니라 계정에 붙어 있어서, 토큰 하나로 내가 소유했거나 '개발 도구' 권한을 받은 봇 모두에 쓸 수 있어요. 어느 봇의 요청인지는 주소에 넣은 봇 id로 가려요. 누구나 읽을 수 있는 봇 정보 조회와 README 배지는 토큰이 필요 없어요.

토큰 만들기#

Hankari Devs 메뉴의 토큰에서 이름을 붙여 만들어요. 봇 등록 5단계에서도 바로 만들 수 있어요.

토큰은 hkd_로 시작해요. 만드는 순간 한 번만 보여 줘요. 한카리는 해시만 저장해서 다시 보여 줄 수 없어요.
한 계정에 10개까지 만들 수 있어요.
토큰 목록에서 마지막으로 쓰인 때와 그때 신호를 보낸 봇을 볼 수 있어요.

토큰 싣기#

Authorization 헤더에 Bearer를 붙여 보내요. Bot hkd_…처럼 Bot을 붙여도 똑같이 받아요.

Authorization: Bearer hkd_0123456789abcdef0123456789abcdef0123456789abcdef

쓸 수 있는 봇#

요청마다 토큰 주인이 그 봇을 다룰 수 있는지 다시 봐요.

토큰 주인	쓸 수 있나요
봇 소유자	네
'개발 도구' 권한을 받은 공동 제작자	네
그 밖의 공동 제작자, 다른 사람	아니요. 없는 봇과 똑같이 404를 돌려줘요.

공동 제작자에서 빠지거나 '개발 도구' 권한을 잃으면 그 사람의 토큰으로는 바로 못 보내요. 봇에는 소유자나 오래 함께할 사람의 토큰을 넣어 두세요.
소유권을 넘기면 이전 소유자는 모든 권한을 가진 공동 제작자로 남아서, 넣어 둔 토큰도 그대로 쓸 수 있어요.
탈퇴하거나 계정이 정지되면 그 계정의 토큰은 모두 쓸 수 없어요.

토큰은 비밀번호처럼 다뤄 주세요. 토큰 하나로 내 봇 모두에 신호를 보낼 수 있어요. 코드 저장소에 올리지 말고, 새었다면 토큰에서 바로 폐기하고 새로 만드세요.

오류 응답#

오류는 HTTP 상태 코드와 함께 error 한 줄짜리 JSON으로 돌려줘요.

401 Unauthorized
{
  "error": "unauthorized"
}

상태	error	뜻
`401`	`unauthorized`	토큰이 없거나, 잘못됐거나, 폐기된 토큰이에요. 예전 봇 토큰(`hk_…`)도 401이에요.
`404`	`not_found`	봇이 없어요. heartbeat에서는 토큰 주인이 그 봇을 다룰 수 없을 때도, 봇 정보 조회에서는 아직 공개되지 않은 봇도 404예요.
`410`	`gone`	없어진 주소예요. `/v1/bots/heartbeat`, `/v1/bots/stats`, `/v1/bots/verify`는 `/v1/bots/{id}/heartbeat`로 바꿔 주세요.

요청 제한#

지금은 요청 횟수를 따로 제한하지 않아요. heartbeat는 1~5분에 한 번이면 충분해요. 제한을 두게 되면 429 Too Many Requests로 알리고, 이 문서에 먼저 적어 둘게요.

heartbeat를 보내는 주기는 가동 상태 › 주기적으로 보내기에 있어요.