OAuth2 API References

Index

사용자 인증 (/oauth2/v1/authorize)

oAuth2.0 의 인증을 시작하는 API 로써 사용자에 대한 로그인 확인 및 처리를 진행하며, 인증이 완료된 후에는 Client 에서 필요로 하는 Scope에 대하여 사용자로부터 확인 및 인가를 받습니다.

Request

GET https://rest.coolsms.co.kr/oauth2/v1/authorize?{client_id}&{scope}&{state}&{redirect_uri}&{response_type}

curl https://rest.coolsms.co.kr/oauth2/v1/authorize?client_id={K00002ACVCC}&scope={users.profile:read}&state={kl3j81881929cvk}&redirect_uri={https%3A%2F%2Fmytestapp.co.kr%2Fcallback}&response_type={code}

Required query parameters

  • client_id - client 등록시에 발급받은 client_id

  • state - client 에서 /oauth2/v1/authorize 요청에 대한 redirect_uri 에서 구분을 할 수 있는 random string 값 (자세히 알아보기)

  • redirect_uri - 인증과 인가가 끝난후에 결과값인 codestate 를 받을 client의 callback uri

  • response_type - code 값을 입력하면 됩니다.

  • scope - access token 으로 사용할 권한들 (자세히 알아보기)

Redirect

사용자에 대한 인증과 권한 인가가 완료된다면 인증시 입력하였던 redirect_uri로 결과값을 전송합니다. 예를 들어, redirect_urihttps://www.mytestsite.com/oauth2/callback 이라면 결과값은 아래와 같습니다.

https://www.mytestsite.com/oauth2/callback?code=l23kj16sdgal1236kn1236s1l236g123k6d126nlaskdnglkandglknsagd&state=alskdnglnl2k36j
  • code - 인증 서버로 부터 발급받는 코드이며, 약 300초 동안만 유효

  • state - 사용자로부터 받은 state 값이며, 이 값을 통하여 client 에서 어떤 요청에 대한 응답인지 구분한다.

Errors

  • ValidationError(400) - 잘못된 parameter 값이 왔을경우

  • InvalidScope(400) - CoolSMS 에서 제공되는 scope 목록에서 없는 경우

  • InvalidHostName(400) - redirect 할 uri 의 host 와 클라이언트 등록할 때 등록한 uri 의 호스특가 다른 경

  • InvalidClientId(400) - 잘못된 client id 를 입력한 경

  • InactiveClient(400) - 클라이언트가 inactive 인 경우

  • InternalError(500) - 서버 오류

토큰발급받기 (/oauth2/v1/access_token)

oAuth2.0 인증 과정에서 토큰 발급을 담당하는 API 로써 grant_type 에 인증 방법이 달라지며 인증이 완료된 경우에 access token을 발급한다.

Request

POST https://rest.coolsms.co.kr/oauth2/v1/access_token

curl -X POST https://rest.coolsms.co.kr/oauth2/v1/access_token -H "Content-Type: application/json" -d '{"client_id": "K0000DAV49C", "client_secret": "skjf8190221lcmzza18j9woiq0", "redirect_uri": "https://mytestapp.co.kr/callback", "grant_type": "authorization_code", "code": "SAMPLECODE" }'

Required body parameters

  • grant_type - access_token발급을 위한 인증 방식. (유효 값: authorization_code, refresh_token, client_credentials)

Conditional required body parameters

  • client_id - client 등록시에 발급받은 client_id (header Authorization에 클라이언트 정보가 없는경우 필수)

  • client_secret - client 등록시에 발급받은 client_secret (header Authorization에 클라이언트 정보가 없는경우 필수)

  • redirect_uri - client 발급 시 입력한 redirect_uri (grant_typeauthorization_code 인 경우 필수)

  • code - 사용자인증(/oauth2/v1/authorize)에서 발급 받은 code값. (grant_typeauthorization_code 인 경우 필수)

  • refresh_token - 기존에 토큰발급('/access_token')을 통하여 발급된 refresh_token. 만료기간이 없고 해당 사용자가 클라이언트에 대한 권한을 Revoke시 파기. (grant_typerefresh_token 인 경우 필수)

  • username - coolSMS 의 userId. (grant_typepassword 인 경우 필수)

  • password - coolSMS 의 password. (grant_typepassword 인 경우 필수)

grantType 에 대한 정리

  • authorization_code - authorization_code grant flow를 통해 발급 받은 코드를 이용하여 access_token과 최초 1회 refresh_token발급

  • refresh_token - 발급받은 refresh_token 을 사용한 access_token재발급

  • client_credentials - 클라이언트 정보를 통한 access_token발급

Response

{ "access_token": "String", "refresh_token": "String", "token_type": "String" }

{ "access_token": "eyUnR5cCI6IkpXVCJ9.eyJleHBpcmVBdCI6IuyYJ9.MJ4CxRIuiuHxFscCHGgio", "refresh_token": "asdglkj153lk.j15kljskdangb.as236dhfasdf125", "token_type": "Bearer" }

  • access_token - CoolSMS 리소스 서버(각 마이크로서비스 서버)에 접근하여 데이터 요청 시 인증을 위한 토큰. 만료기간은 24시간.

  • refresh_token - access_token을 재발급 하기 위한 토큰. 사용자가 클라이언트를 Revoke 하지 않으면 영구적으로 사용가능.

  • token_type - 리턴 받은 token의 타입

Errors

  • ValidationError(400) - 유효하지 않은 파라미터 혹은 필수 파라미터 누락

  • InvalidGrant(403) - 유효하지 않은 인증정보

  • InvalidClient(400) - 유효하지 않은 클라이언트

  • InvalidRefreshToken(400) - 유효하지 않은 refresh_token 파라미터

  • InternalError(500) - 서버 내부 오류