본문으로 건너뛰기

API Key 인증 방식

REST API를 요청(Request)할 때 HTTP 헤더에 Authorization 정보를 추가하여 인증 받을 수 있습니다. API를 요청한 계정의 소유자를 확인하는데 필수적인 절차입니다.

참고

Authorization 헤더정보를 전달하는 방식은 HTTP에서 인증을 위한 수단으로 널리 사용되고 있습니다. Basic access authentication 을 참고하세요.

쿨에스엠에스 API Key 관리 페이지에서 API Key와 API Secret을 생성하여 REST API 호출에 사용합니다.

Request​

형식

`Authorization: <AuthenticationMethod> apiKey=<API Key>, date=<Date Time>, salt=<Salt>, signature=<Signature>`

예시

`curl -X GET https://api.coolsms.co.kr/messages/v4/list --header "Authorization: HMAC-SHA256 apiKey=NCSAYU7YDBXYORXC, date=2019-07-01T00:41:48Z, salt=jqsba2jxjnrjor, signature=1779eac71a24cbeeadfa7263cb84b7ea0af1714f5c0270aa30ffd34600e363b4"`

<AuthenticationMethod>
Signature 생성 알고리즘으로 HMAC-SHA256, HMAC-MD5 중에 하나를 선택할 수 있습니다.

<API Key>
발급받은 API Key를 입력합니다.

<Date Time>
ISO 8601 규격의 날짜와 시간을 입력합니다.

<Salt>
12 ~ 64바이트의 불규칙적이고 랜덤한 문자열을 생성하여 사용합니다.

<Signature>
<Date Time>과 <Salt>를 하나로 연결한 문자열을 데이터로 하고 API Secret을 Key로 만들어진 HMAC 해시코드

Signature의 재사용을 막기위해서 입력된 <Date Time>의 표준시간을 기준으로 ±15분 차이가 날 경우 RequestTimeTooSkewed 오류를 리턴합니다. 또한 15분 내에 한번 사용된 Signature는 중복사용이 불가능하므로 원천적으로 재사용을 차단하고 있습니다.

참고

  • 날짜와 시간을 표현하는데 있어서 시차와 표기법이 틀릴 수 있으므로 혼돈이 없도록 국제규격 ISO 8601을 따릅니다. ISO 8601 을 참고하세요.

Signature 생성​

클라이언트에서 <Date Time> + <Salt> 를 데이터로, API Secret을 Key로 사용하여 HMAC(Hash-based Message Authentication Code)을 만들어진 Signature를 서버로 보내면, 서버 쪽에서도 동일한 방식으로 만들어 비교하게 됩니다. API Secret은 Signature를 생성할 때만 사용하고 외부에 노출되지 않도록 주의해야 합니다.

참고

  • 메시지의 무결성 검증(인증)을 위한 용도로 Signature 생성 및 검증에 Hash기반의 MAC 알고리즘을 사용하고 있습니다. Hash-based message authentication code 을 참고하세요.

Signature는 중복사용이 불가하며 15분 안에 전송되는 요청(Request)의 Signature 값은 항상 달라야 합니다. 그래서 Salt는 매번 요청때마다 다른 문자열로 변경하여 요청 시간대가 같아도 항상 Signature가 다른 값으로 생성되도록 합니다.

  • InvalidAPIKey
    • 유효한 API Key가 아님
    • HTTP Status Code: 403
  • SignatureDoesNotMatch
    • 생성한 Signature가 일치하지 않음
    • HTTP Status Code: 403
  • RequestTimeTooSkewed
    • 시간 값이 서버 시간을 15분 이상 벗어남
    • HTTP Status Code: 403
  • DuplicatedSignature
    • 15분 안에 동일한 signature 값
    • HTTP Status Code: 403